Most API modules provide one or more of the methods:
These method names are reserved and it's guaranteed that if a module has one of these, it will conform to the standards described below.
Create method is used to create a new object (service,
It will expect the named object attributes in input.
Create attributes are always a subset of the values returned by
It will output an
id - the identifier of the newly created object.
Read method returns information about an object based on its identifier (
It expects an
id and returns the object with this ID.
Read methods may define additional
with argument that is an array of extra items' symbols that you want to fetch with the object.
you can fetch a service type with the features supported by it (see ServiceType::Read).
Find is used to retrieve a list of objects of a type. Find can be supplied with the following arguments:
How many objects to return at most.
If not specified,
Find will return all objects.
How many objects to skip before starting to return.
limit it can be used to implement pagination
The array of filters to apply to the results.
It is an array of objects containing the
field is one of the object fields (see
Find's documentation in the module to see what fields are filterable),
type is one of
argument is the value to which the field is compared.
The array of ordering fields,
starting with the most important one.
Each element is an object with 2 fields:
field - the name of object's field to order by (see module's documentation to see what fields are orderable) and
direction - either
Same as in
an array of extra elements' symbols.
Symbols available for
Find may be different than those available for
Find returns an object with fields:
The results array.
The number of the results that would be returned if there was no
limit set (useful when implementing pagination for calculating the number of pages).
For performance purposes,
the objects returned by
Find may not contain all fields that are returned by
however they will always be a subset of them.
Refer to the module's documentation for an exact list of returned fields.
This method is used to modify an existing object with a specific ID.
It will always require the
id argument to identify the object,
and one or more object fields with the new values.
Available fields are a subset of the fields returned by
Some fields (for example service type) are available to only when creating the object with
Create and cannot be modified later (such as service's type).
As a special case,
Update with just the object's
id checks if the object exists and modifies nothing.
This method requires the
id argument containing the object's ID.
It deletes the object.
It may also delete other objects (for example,
deleting a group deletes all its services),
see the module's documentation for details.