A screen on an API endpoint
A screen does not need a database behind it. It can read the rows an API returns and save through the API's own calls: the grid, the filters, the record form, the actions, the permissions and the AI assistant work as on any screen, and every save goes through the application that owns the data — with its rules, its defaults and its messages.
Two set-ups:
| Set-up | Read | Save |
|---|---|---|
| A screen on an API | An endpoint | Endpoints |
| Saves through | An SQL query — fast, every column, paging | Endpoints of another connector |
At a glance
Read an endpoint
In the Screen Designer, stage Data: choose the API connector as Connector, then the endpoint as Read query. The list offers the endpoints that say where their rows are (Rows, in the endpoint editor).
The grid is the same. Its columns are named by the endpoint; their labels come from the screen, then the dictionary, then the server's own titles. The page is titled by the screen's label.
Filters
- The endpoint's parameters are shown above the grid — their example as a placeholder, their help as a tooltip, a dropdown for a closed list of values. A parameter that has a filter column of the same name goes to the filter panel instead.
- Every column flagged as a filter is in the advanced filters, with the operators of a query — contains, equals, not equals, starts with, ends with, a range — and a pick-list when the column has an enum or a lookup. These filters apply to the rows the endpoint returned.
- A screen's own parameters — the header of a detail form — can be required, so that the endpoint is never called on a blank header.
Row limit
The number of rows is the endpoint's, capped again by the screen, without paging. When the endpoint names its Row limit parameter, the screen fills it from its own Max rows. The screen says the result is truncated when the server says there is more. Sorting and grouping happen on what was returned.
A server that has nothing to list
Some servers answer an error when a list is empty. The endpoint can name the refusals that mean no rows: the screen then shows an empty list instead of an error.
Save through endpoints
Update query, Insert query and Delete query name endpoints marked Changes data. The grid and the record form save as they always do:
- the values of the row go to the endpoint's parameters by name; the value a row held when it was loaded is available as
<COLUMN>_ORIGINAL; - the screen's own parameters go with every save;
- what the server refuses is the save's error, in the server's words; its warnings come back with the save;
- a value the endpoint returns — a number the server assigned — comes back to the form;
- a column the screen does not send is left alone by the server; a column the user cleared is sent blank;
- on a change, only what the user changed is sent to an endpoint served by a function.
The notification rules fire, and the assistant's write tools go through the same save.
Saves through — read by SQL, save by API
When the data can be read from a database but must be written through the application — a JD Edwards form, an ERP's API — keep the screen on its query and choose the API connector in Saves through. The update, insert and delete then name endpoints of that connector.
No mapping is written: a parameter of the endpoint takes the value of the column of its name, else of the column that carries the same dictionary item (ALPH from ABALPH).
The read stays fast and complete; the save applies the application's own rules. Integrity, Find usages, renaming and packages follow the save connector.
What differs from a screen on a query
| On a query | On an endpoint |
|---|---|
| Paging by the server | The endpoint's row limit, no paging |
| Filters translated to SQL | The endpoint's parameters, then filters on the rows returned |
| Import of rows | Not available |
| Configured workbook export | Not available — the grid's own export works |
| Server-side summary | Not available |
| Audit mirror, change packages on its saves | Not available |
| Dictionary write rules (sequence, login, date) | The server decides |
| Source of a Data Explorer model | Not available |
Access
The permission is the endpoint's — api:<connector>:<endpoint> — for the read and for each save; a screen whose read endpoint the user may not call is not in their menu. The screen's editable when rule is enforced, and the caller's data scope applies to the rows returned.
In packages
A screen travels whole: the endpoints it reads or saves through are listed under API endpoints in a package, ticked by default like its queries; an endpoint served by a service brings that service with it. The screen's history records them too.
Tips & best practices
- Read by SQL and save by API whenever both are possible: the best of each.
- Declare the endpoint's error fields: a refused save must look like one.
- Flag as filters the columns people search on; name the row limit parameter so that Max rows drives the server.
- Let a generator build the screen when one exists — Create from… creates the endpoints and the screen together.