API endpoints
An endpoint is one named call of an API connector: submit this report, read these customers, create an order. Once declared it is used everywhere without a line of code — as the source of a screen, in a screen action, a service, a job step, a test, by the AI assistant, or by an outside caller — and each endpoint has its own permission.
Access: Liberty Next → Data → Connectors, an API connector, tab Endpoints.
At a glance
The list
The endpoints are listed in alphabetical order, with a search box once there are more than five (name, label, path, method, description, group). Endpoints that share a group sit under its heading, which folds and shows their number.
Each card starts with a pill — the HTTP method, FN for an endpoint served by a function, ACT for one served by a service — then the name, the label, and the tag changes data where it applies.
| Button | Does |
|---|---|
| Add endpoint | Asks for a name and opens a blank endpoint. |
| Create from… | Writes an endpoint from what the server describes — see below. Shown when the connector has generators. |
| Check N generated | Asks the server again for each generated endpoint and lists those that no longer match. |
The Test tab runs any endpoint against the connector as it is on the page, without saving: its parameters as fields, then the result.
The four stages
An endpoint is drawn as four cards — What it is → Inputs → The call → The answer — each saying what it holds; the fields of the picked stage are beside it.
What it is
| Field | Meaning |
|---|---|
| Name, Label, Description | The identifier used by actions and permissions, the short label of the lists, one sentence of description. |
| Changes data | Tick it when the call submits, creates or runs something — see Endpoints that change data. |
| Group | The heading the endpoint is listed under. Display only. |
| Created from | For a generated endpoint, what it was created from, with Refresh from the server. |
Inputs
Each parameter is a line — its name, its label, its default, Required — opened to edit it.
| Field | Meaning |
|---|---|
| Name, Label | The {{NAME}} used in the path, the headers or the body, and the label of its field. |
| Default value | Taken when the caller leaves the parameter out or blank. |
| Example, Help — what to put in it | Shown under the field wherever the endpoint is filled, and given to the AI assistant. |
| Allowed values | A closed list: the field becomes a dropdown, another value is refused before anything is sent, and the letter case is corrected. |
| Required | A call without it is refused before anything is sent. |
The call
Method and URL path, Extra headers, Content-Type, Body (with Format JSON) and Query params. Leave out a query parameter whose value is blank sends only the query parameters that have a value, for a server that reads an empty one as a filter on nothing.
Instead of an HTTP call, the endpoint can be Served by a function or Served by an action — see below.
The answer
| Field | Meaning |
|---|---|
| Rows | Where the list of records is in the answer. With it, a screen can read the endpoint as it reads a query. |
| Columns | Column name = key of a record (AN8=z_AN8_19): the columns, in order, named so that the dictionary recognises them. |
| Column titles | Where the answer gives each key its title — the label of a column neither the screen nor the dictionary names. |
| Row limit parameter | The parameter that carries the maximum number of rows: a screen fills it from its own Max rows. |
| "More rows" flag | Where the server says there is more than it returned: the screen then says the result is truncated. |
| Error fields | Where the server puts its errors when it answers 200 all the same: something there makes the call a failure, with that content as its error. |
| Warning fields | Where the server puts its warnings: reported with the answer, the call stands. |
| Response field, Response mappings | The part of the answer returned, and logical names mapped to paths of the answer. |
A path may end with a filter on the items of a list — result.errors[errorLevel=1] — for a server that puts its errors and its warnings in the same list.
Create from…
A generic endpoint — run any report, with JSON for whatever depends on the report — is hard to fill. When the application behind the connector provides generators, Create from… writes a dedicated endpoint instead:
- Find the object on the server.
- Answer a few questions — which columns, which options.
- Create the endpoint: one named parameter per input, with its label, its help and its default. It is added unsaved and opened for review.
A generator can also build several endpoints at once, or a whole screen: the dialog then asks for the application, the screen identifier, its title and whether to add it to the menu, and creates the endpoints and the screen in one validated pass — nothing is written when anything is invalid. An endpoint that already exists is kept as it is and used by the new screen, unless Replace the N endpoint(s) that already exist is ticked.
A generated endpoint remembers what it was created from. Refresh from the server builds it again and shows what changes before applying it: the address, the body and the parameters follow the server; the name, the label, the description and what was written on a parameter that stays are kept.
The generators of the JD Edwards AIS connector are described in Nomajde — Create from….
Endpoints that change data
An endpoint marked Changes data is treated apart:
- a screen can name it as its insert, update or delete — see A screen on an API endpoint;
- the AI assistant does not call it like a read: it needs the API tool and the Write tools switched on in Administer → App → AI Assistant, a user allowed to change data through the assistant, and it proposes a card in the chat — nothing is sent until the user applies it. Over MCP, Allow changes over MCP is needed as well;
- the call is recorded in the AI usage like the other changes made through the assistant.
An endpoint that is not marked is treated as a read: mark every endpoint that writes.
Served by a function
One HTTP call cannot do everything: changing a record a server only offers through a form means finding it, checking that exactly one was found, then acting. Served by a function names a function of an application's plugin that answers instead of the HTTP call. Its arguments are the endpoint's parameters; its answer is treated like a response — rows, error and warning fields, mappings, Changes data. For a screen, an action, a job or the assistant, it is an endpoint like any other.
Served by a service
Served by an action names a service: its steps — queries, other endpoints, functions, conditions, loops — run on the server and answer as one endpoint. The endpoint's parameters are the service's inputs; what the service returns is the answer. It runs with the endpoint's permission: who may call the endpoint runs its steps. Expose, on the Services page, creates such an endpoint in one click.
Permissions and safety
Each endpoint has its permission, api:<connector>:<endpoint>: a role can be allowed one report or one orchestration, not all of them. The permission holds because a value can never redirect a call:
- in the path, a value cannot climb out of the endpoint's path nor give another address;
- in a JSON body, a value placed inside a string stays inside that string;
- in a form body, a value cannot add a pair;
- a file sent by a call made on behalf of a user stays inside the folder the endpoint names.
A call that would break one of these rules is refused before anything is sent.
What the caller sees on a failure
- A server that cannot be reached is named with its address: cannot connect to https://host:8999 — check the connector's base URL.
- An HTTP error carries the server's own words when the error fields find them.
- A list that is not where the endpoint says is an error naming what the answer holds, not an empty screen.
Tips & best practices
- Write the help and the example of every parameter: they serve the people who fill the form and the assistant alike.
- Prefer several specific endpoints to one generic endpoint with JSON: each gets its permission and its form.
- Declare the error fields of any server that answers 200 with its errors inside; otherwise a refused save looks like a success.
- Group the endpoints of one application or one subject under a heading.
- Cover the endpoints the business depends on with tests.
Related
- Connectors — the connector itself: address, authentication, environments.
- A screen on an API endpoint · Services · Tests
- REST API