Aft's API supports reading and mutating data in the datastore using a rich JSON API.
Every call uses an HTTP POST with a JSON body (and 'application/json' Content-Type).
The routes are exposed in the following URL format:
So for example, to perform a
findMany on the
model model, one would send an HTTP POST to
findMany both return records from the Aft datastore. Both return an object with a single key, "data".
findOne returns as "data" a single record as a JSON object, whereas
findMany returns an array.
Both operations accept a JSON object as a parameter describing the query. At the top level, the request must have a key, "where", which must be an object.
The where object may contain keys referencing the fields (i.e. attributes or relationships) of the model being queried. The values of those keys represent equality filters. For example, to query for a user named Andrew, one might send:
Where clauses may be applied to relationships as well, in which case Aft accepts a nested "where" object. For example, if user object has a related "profile" object with a "bio" field, one might query:
For relationships with Mutli cardinality, an aggregate must be specified. For example, if a user has a related collection of posts:
The supported aggregations are "some", "every" and "none".
A typical client UI requires data not just from a single record, but also a graph of related records.
In order to support efficient and transactional loading of these record graphs, Aft supports "includes".
Includes are peers to the "where" object at the top level of a
Includes may be similarly nested.
For efficiency, clients may request only a subset of fields on a record by using a "select" object. Selects may also specify records being included, though only one or the other can exist on the same level of nesting.
Count accepts the same arguments as a
findMany call, but returns an object with a single key, "count", that has as its value a number representing the number of records that would've been returned from the equivalent findMany.
The mutation methods are similar to the read methods.
Create accepts a single key "data". All records in Aft have an implcit id field which is always a server-generated UUID4. Thus it is omitted from the create call.
Nested related objects may be mutated—created, updated, connected, disconnecting, set—in the same call.
So to create a user:
Updates take two arguments: a "where" object to locate the record to be updated, and "data" describing the mutation.
Updates accept the same set of nested mutations.
Deletes just accept a where.
And upserts accept a where object and two possibilities. A create, taken in the event that no record maches the where object and an update in the opposite case.