As explained in the previous section, an APIMAS specification contains structural elements with their respective metadata. This metadata are prefixed with a dot ‘.’ and called Predicates. Predicates add semantics to their parent structural elements and therefore, it is a way to change the behaviour of your application.
APIMAS defines a set of predicates whose semantics are understood from every application (both client and server side) and help you create your specification. Below, there is a list of the widely-known predicates:
The predicates listed below describe basic structural elements of your REST application.
Predicate | Description |
---|---|
.endpoint |
It defines a location to the web after which there is a set of collections to interact. |
.collection |
It defines that the parent node is a collection of resources of the same type, where each resource can be related to other resources, it is described by some data, and there are actions that can be performed on it. |
There are also predicates which delineate what actions or methods can be performed on a collection or a resource individually.
Predicate | Description |
---|---|
.list |
The list of resources contained to the collection is permitted. It corresponds to: GET <collection name>/ |
.retrieve |
A single resource can be retrieved and viewed. It corresponds to: GET <collection name>/<pk>/ |
.create |
A new resource of the type defined by the collection can be created. It corresponds to: POST <collection name>/ |
.update |
A single resource can be updated. It corresponds to: PUT <collection name>/<pk>/ PATCH <collection name>/<pk>/ |
.delete |
A single resource can be deleted from the set of existing. It corresponds to: DELETE <collection name>/<pk>/ |
Note
The .update
predicate allows a single resource
to be both replaced and partially updated.
Action predicates are specified inside the structural element actions of a collection definition.
Example:
{
'foo': {
'.collection': {},
'actions': {
'.list': {},
'.retrieve': {},
}
}
}
In the above example, only retrieve and list operations are permitted for collection ‘foo’.
Each resource contained in a particular collection is described by a field schema with properties and data associated with it. Specifically, each resource is described by a set of fields with specific type and behaviour.
Similarly to the structural and action predicate, there are also predicates to describe the properties of every field. These predicates slit into two categories: a): types, b): properties.
Predicate | Description |
---|---|
.integer |
Parent node is an integer. |
.float |
Parent node is a floating point number. |
.string |
Parent node is a string. Small to middle sized strings are supported.
|
.text |
Parent node is a text. |
.boolean |
Parent node is either true or false. |
.email |
Parent node is an email address. |
.serial |
Parent node is a serial, non-writable integer number. |
.choices |
Parent node can take a list of allowed values as specified
by the parameter
|
.ref |
Parent node points to the web location of another resource.
|
.identity |
Parent node points to the web location of this resource. It’s actually the REST identifier of the resource. It is non-writable. |
.file |
Parent node is a file. |
.date |
Parent node is a date, represented by a string.
|
.datetime |
Parent node is a datetime, represented by a string.
|
.struct |
Parent node is a structure which consists of another field schema, i.e. a set of fields with their types and properties.
|
.structarray |
Parent node is an array of structures.
|
Note
Every field must be described with at most one type.
Properties predicates, typically, describe the behaviour and how can be used on the various actions.
Predicate | Description |
---|---|
.required |
The parent node is required and must be included in every API call associated with create and update operations (e.g. POST and PUT requests). |
.readonly |
The parent node is read-only and its value can be viewed, but it cannot be modified or set. |
.writeonly |
The parent node is write-only and its value can be modified or set, but it cannot be viewed. |
.nullable |
The parent node can have null values. |
Note
Some predicates are mutually exclusive. Specifically a
node cannot be described as both .readonly
and writeonly
or .required
and .readonly
.