Atomic Endpoints
URL: https://atomicdata.dev/classes/Endpoint
An Endpoint is a resource that accepts parameters in order to generate a response. You can think of it like a function in a programming language, or a API endpoint in an OpenAPI spec. It can be used to perform calculations on the server side, such as filtering data, sorting data, selecting a page in a collection, or performing some calculation. Because Endpoints are resources, they can be defined and read programmatically. This means that it’s possible to render Endpoints as forms.
The most important property in an Endpoint is parameters, which is the list of Properties that can be filled in.
You can find a list of Endpoints supported by Atomic-Server on atomicdata.dev/endpoints.
Endpoint Resources are dynamic, because their properties could be calculated server-side.
When a Property tends to be calculated server-side, they will have a isDynamic property set to true, which tells the client that it’s probably useless to try to overwrite it.
Incomplete resources
A Server can also send one or more partial Resources for an Endpoint to the client, which means that some properties may be missing.
When this is the case, the Resource will have an incomplete property set to true.
This tells the client that it has to individually fetch the resource from the server to get the full body.
One scenario where this happens, is when fetching Collections that have other Collections as members. If we would not have incomplete resources, the server would have to perform expensive computations even if the data is not needed by the client.
Invite Endpoint
The /invites endpoint handles stateless, signed invite tokens. These tokens are generated and signed by the inviter’s private key and can be verified by the server without any stored state.
The endpoint accepts a token query parameter (base64-encoded signed JSON) and an optional public-key parameter.
When a public-key is provided, the server derives a DID-based Agent (did:ad:{publicKey}) from it, grants the requested rights to that Agent, and responds with a Redirect to the target resource.
When no public-key is provided and the request is unauthenticated, the endpoint returns information about the invite (target, rights, expiration) so the client can prompt the user.
Design Goals
- Familiar API: should look like something that most developers already know
- Auto-generate forms: a front-end app should present Endpoints as forms that non-developers can interact with