Skip to main content

Protocol

Principles​

ACTITO APIs are REST APIs

Each API contains a bunch of operations, each operation provide a specific operation among the module it belongs to. For every kind of operation (retrieve list, retrieve single item, create new item, update an existing one etc.) we try to use a similar protocol so as to ease understanding and reusability.

Routes​

Every route describes an operation on an ACTITO "resource". An operation should be over data (retrieve, creation, modification, deletion) or an action triggering (launch or activate a campaign, start a workflow etc.)

Every ACTITO resource is linked to an ACTITO entity that is usefull for access limiting (see ACTITO entity concept).

In consequence, every route starts with /entity/{e} where {e} is the name of an ACTITO entity.

Ex : GET /entity/demo/table returns the list of profile tables that belongs to the "demo" ACTITO entity.

HTTP Methods​

  • GET:

For retrieving resource data (item lists or single item).
Data modification will never result of a GET operation.

  • POST:

For new resource item creation or action triggering.

  • PUT:

For resource item update.
Provided data will usually replace the whole resource referenced by the operation (specific behavior are described in concerned operations documentation).

  • PATCH:

For resource partial update.
Only provided fields will be impacted by a PATCH call. Not mentioned fields will be left unchanges.
Providing a field with a null value means you aim to remove the potential existing value of the resource.

  • DELETE:

For single resource item deletion.

Requests and responses​

Data to provided for creation or update and data returned by the operations are always plain JSON objects or arrays.

Requests may always include Content-type and Accept headers with "application/json" value.

Query string parameters

Those parameters should never affect the resource on data modification operations.
Query string parameters are only used for "Get list of" operations to specify filtering (criteria on field values, pagination and sorting when available).

Return codes​

The result of an operation is stated by the HTTP return code the call receives.

Every operation can return a subset of existing http return codes.

The principle is to always return the same code when an operation has the same result so as you can easily understand what went right or wrong for your call.

  • 2XX return codes state that the operation has been successful

  • 4XX return codes state that the server understood the request but operation could not be processed due to wrong data or wrong state (authentication, conflicts etc.)

  • 5XX return codes correspond to internal error you can not affect by yourself (network issue, bug etc.)