Back to docs · Beta
When to use it
An upstream JSON API returning an array of objects, where you want a stable contract and metering in front of something you do not control.
What to grant
Issue a dedicated token for EndpointOS with the narrowest scope the endpoint needs, so it can be revoked without affecting other integrations.
Setup
1. Find the collection endpoint
EndpointOS reads a list from base URL plus resource path, and a single record from that path plus /{id}. The response should be a JSON array of objects, or an object with the array under a data or results key.
2. Create a token for EndpointOS
If the upstream needs auth, issue a token specifically for this integration and note the header it expects, for example Authorization or X-Api-Key.
3. Connect it in EndpointOS
Create a resource, choose REST API, and enter the base URL, resource path, and the auth header name and value if needed. The header value is encrypted at rest.
What you will be asked for
- Base URL: The origin of the upstream API, without a trailing path. Must be https and must resolve to a public address.
- Resource path: The collection path appended to the base URL, for example /v1/orders. Records are read from this path and single records from /path/{id}.
- Auth header name (optional): Optional. The header the upstream expects, for example Authorization or X-Api-Key.
- Auth header value (optional), stored encrypted: Optional. The value sent in that header, for example a bearer token. Stored encrypted and never returned.
What the API supports for this source
Generated from the same declaration the API enforces on every request, so it cannot promise something a request would be rejected for.
This source forwards your query rather than applying it. EndpointOS relays filters and paging to the upstream API and cannot know whether the upstream honours them. Verify against your own upstream before publishing a contract that depends on them.
| Filtering | equals on any declared field, forwarded to your upstream, which decides whether to honour it |
|---|---|
| Sorting | Not supported |
| Search (q) | Not supported |
| Writes | create, update, delete |
| Paging | limit and offset, forwarded to your upstream. If it paginates by cursor, these have no effect |
| Record count | Approximate: the total reflects the page |
Worth knowing first
- Filters and pagination are FORWARDED to the upstream, not applied by EndpointOS. If the upstream ignores limit and offset, or paginates by cursor, paging will not behave as the contract suggests. Verify against your upstream before publishing.
- Record counts are not exact: the total reflects the page length, because upstream pagination shapes vary too much to infer.
- Only https URLs resolving to public addresses are allowed, and the URL is re-checked on every request.
If something goes wrong
The same first page repeats as you page
Why: The upstream does not honour the forwarded limit and offset parameters, likely because it paginates by cursor.
Fix: Point the resource at an endpoint that accepts offset paging, or put a small adapter in front of it. EndpointOS cannot translate pagination shapes it cannot see.
Filters seem to be ignored
Why: The upstream does not recognise the query parameter names being forwarded.
Fix: Check what the upstream expects. EndpointOS forwards field=value pairs and cannot know an upstream's own filter grammar.
URL refused
Why: The base URL is not https, or resolves to a private or loopback address.
Fix: Use a public https endpoint.