Introduction to APIs

What is an API?

An API, or Application Programming Interface, is a way to allows to have a server - client interaction between two different applications. By this interaction, an API will provide a way to extract some datas, or interract with it by doing creation, update or deletion actions.

How it works

APIs are caracterized by a specific URI and method to use them. Parameters can also be passed on in the URI (path or query parameters) or the body of the request. Depending on the query sent, response from the server be different, but will respect the response format expected and described in its documentation.

Accessing Zetaly APIs

To access the the Zetaly APIs, do the following:

1. In the top right corner of the Zetaly Portal, click the Data API () icon.
   A DATA API page appears containing panels for each of the installed Zetaly modules.
   
2. Each Zetaly module has a specific page with all its APIs. To access all the APIs of a Zetaly module, click on the Show APIs link within the panel of the Zetaly module of interest.
   An API page appears in a new tab corresponding to the Zetaly module of interest (in our example the ZRP module, and thus the ZRP API page).
   

The top of the API page displays the version of the Zetaly module.
The middle of the API page lists all the API methods (GET, PUT, POST, DELETE, PATCH) grouped by functionality. Each functional group has a title and description (in the example above, the Generic Reference functional group).
By default all of the functional groups are expanded, listing the associated APIs. You can collapse each functional group (to hide its associated APIs) by clicking the button.
By default each API is collapsed. You can expand the API to view its parameters by clicking the button. In the example above, the GET method for obtaining the statistics for a specific CPC and interval is expanded.
The bottom of the API page lists all the associated schemas within a Schemas area.

By default, the associated schemas are collapsed. You can expand each of the associated schemas by clicking its button.
The associated schemas define the structure of the data types that can be used with the API methods. In the example above, the schema associated with capping within the ZRP module (APICapping) is expanded.

Understanding and Using an API

This section describes the general interface usage for using and executing an API request. Some actual examples of using the APIs for the different modules can be found within this article.
Each API has the following information (from left to right) :

• Method (GET, PUT, POST, DELETE, PATCH, ...)
• Relative path to the API (the element surrounded by curly brackets {} are parameters)
• Description

To expand an API and view its parameters click the button.

The Parameters area lists of all parameters associated with the API. These parameters can be in the API path or in the API request.
If the API method is GET or DELETE, it is not possible to have a request body. In this case, the API's parameters are defined by pre-defined fields and drop-down fields (see the example screenshot for obtaining the statistics for a CPC during specifed interval in the Accessing Zetaly APIs section above).
If the API method is PUT or POST, it is possible to have a request body, and the Request body area may exist. The Request body area contains an Example Value of the expected JSON format for the request body. By default the example values are displayed for the JSON's data types, however you can also review the schema associated with the API. To have more information about a property of the JSON you can click Schema. The schema appears in an expandable tree letting you see the schemas used by the API, along with their parameters and possible values.
Clicking the Try it out button updates the Parameters area letting you define the parameters for the API request. When you make changes to the example parameters, the Reset button appears. Clicking on the Reset button reverts the parameters back to the example values.

When you define the API parameters you must also define your user token in the token field. For more information about obtaining your user token, see the Obtainaing the Token Parameter section.
Once you have defined the API parameters and user token, clicking the Execute button results in sending the API request, and the Responses area updates accordingly. The example below shows creating a new catalog element called Catalog sample 2.

Obtaining the Token Parameter

The token parameter must be specified in all of our APIs. It is linked to your Zetaly user credentials and is active during a specific time. It is a security measure to prevent unauthorized users to use APIs.

You can retrieve this token via the ZHB login API as follows:

1. In the top right corner of the Zetaly Portal, click the Data API () icon.
2. In the DATA API page that appears, click Show APIs in the ZHB panel.
3. From the ZHB API page that appears, within the Public Resource functional group, expand the API POST method /zhb/api/v1/users/public/login.
   
4. Click the Try it out button.
   The Request body area updates with editable properties.
   
5. Modify the properties within the Request body area so that only the username and password properties exist, specifing the username and password of your Zetaly Portal user credentials; The last password property does not have a trailing comma (,) at the end of the line.
   
6. Click Execute.
   The Response body area within the Responses area displays two tokens properties. The first token property is associated to the BI role of the user, and is not used with our APIs. The value of the second token property as highlighed below is the token that you must use with our APIs.
   
7. Copy the token to the clipboard. Then paste it into the token field when using any of our APIs.