<<

Special methods

Most API modules provide one or more of the methods: Create, Read, Find, Update and Delete.

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

The Create method is used to create a new object (service, group, address etc.). It will expect the named object attributes in input. Create attributes are always a subset of the values returned by Read. It will output an id - the identifier of the newly created object.

Read

The Read method returns information about an object based on its identifier (id). It expects an id and returns the object with this ID. Some Read methods may define additional with argument that is an array of extra items' symbols that you want to fetch with the object. For example, you can fetch a service type with the features supported by it (see ServiceType::Read).

Find

Find is used to retrieve a list of objects of a type. Find can be supplied with the following arguments:

• limit

  How many objects to return at most. If not specified, Find will return all objects.

• offset

  How many objects to skip before starting to return. Together with limit it can be used to implement pagination

• filters

  The array of filters to apply to the results. It is an array of objects containing the field, type and argument fields. 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 equals, greater_than, lower_than, not_greater_than, not_lower_than and contains, argument is the value to which the field is compared.

• order

  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 ascending or descending.

• with

  Same as in Read, an array of extra elements' symbols. Symbols available for Find may be different than those available for Read.

Find returns an object with fields:

• elements

  The results array.

• total

  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 Read, however they will always be a subset of them. Refer to the module's documentation for an exact list of returned fields.

Update

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 Read. 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, calling Update with just the object's id checks if the object exists and modifies nothing.

Delete

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.

<<