Format of requests and responses

The endpoints available in the Web API require request parameters and return different responses depending on the associated operation.

Although there are endpoints that provide specific operations for certain entities, depending on the business logic of these entities, the input parameters and results are designed for the following main operations:

• Creating a record (POST);
• Updating the attribute of a record (PUT);
• Cancelling a record (DELETE);
• Viewing a record (GET);
• Listing all records (GET);
• Listing a page of records (GET).

Parameters

Mandatory parameters for all endpoints

All endpoints have the following base URL:

https:///api/{account}/{subscription}/{module}/{resource}

The following parameters are always required in all Web API requests and are defined in the URL:

• account: customer account identifier.
• subscription: customer subscription identifier.

To ensure the authentication of the user and the application, it is also necessary to always include the following values in the request headers:

• Authorization: the token obtained from the authentication request.
• Accept: with the application value.

More information: What is the Web API?

Mandatory parameters by type of operation

Other parameters depend on the type of operation associated with the endpoint. Depending on the parameter, it must be specified in the URL, in the query string, or in the body of the message.

Result by type of operation

The response of each request is always a status code that indicates the status of the operation and, optionally, a result in the body of the message. These two results also vary by type of operation.

Types of operations

Creating a record (POST)

URL:

https:///api/{account}/{subscription}/{module}/{resource}

Parameters:

• In this case, the only parameter is the record to be created itself, serialized in JSON, in the body of the message.

Expected status code:

• 201 (Created): indicates that the record was successfully created

Expected result:

• The identifier of the new record, serialized in JSON, in the body of the message.

Updating an attribute of a record (PUT)

URL:

https:///api/{account}/{subscription}/{module}/{resource}/{key}/{attributeName}

Parameters:

• key: the identifier or key of the record to be updated
• attributeName: the name of the attribute to be updated
• The new attribute value, serialized in JSON, in the message body

Expected status code:

• 204 (NoContent): indicates that the record was successfully updated

Expected result:

Canceling a record (DELETE)

URL:

https:///api/{account}/{subscription}/{module}/{resource}/{key}

Parameters:

• key: the identifier or key of the record to be deleted

Expected status code:

• 204 (NoContent): indicates that the record was successfully cancelled

Expected result:

Searching for a record (GET)

URL:

https:///api/{account}/{subscription}/{module}/{resource}/{key}

Parameters:

• key: the identifier or key of the record to search for

Expected status code:

• 200 (OK): indicates that the record was successfully returned

Expected result:

• The selected record, serialized in JSON, in the body of the message

Listing all records (GET)

URL:

https:///api/{account}/{subscription}/{module}/{resource}

Parameters:

Expected status code:

• 200 (OK): indicates that the records were returned successfully

Expected result:

• The list of records, serialized in JSON, in the body of the message

Listing a page of records (GET)

URL:

https:///api/{account}/{subscription}/{module}/{resource}?page={page}&pageSize={pageSize}

Parameters:

• page: the number of the page to be retrieved
• pageSize: the number of records to be retrieved in the result

Expected status code:

• 200 (OK): indicates that the records were returned successfully

Expected result:

• The list of records, serialized in JSON, in the body of the message

Special results

The results documented are the situations where the request was successful and the endpoint was executed without errors, performing the expected operation. The Web API returns different codes in case of error and, in such cases, it can return other results with information about the errors (for example, when the validation of parameters fails).

You can find more information on these scenarios in the following document:

• Error Messages