API Endpoint and URL

You access the resource by sending an HTTP request to the Deepser API server. The server replies with a response that contains either the data you requested, or the status indicator, or even both.
Common characteristics of Deepser REST API resources are as follows: (deepserhost is your domain)

• To access the API you have to call the endpoint at: 

http[s]://deepserhost/api/rest/

• You request a particular resource by adding a particular path to the base URL that specifies the resource.
• The server replies with a response that contains either the data you requested, or the status indicator, or even both.

REQUEST STRUCTURE

All URLs in REST API have the following base URL.

http[s]://deepserhost/api/rest/

Example:
Supposing you want to retrieve the list of Companies from Deepser.
To do this, you need to use the GET HTTP method.

The GET request to retrieve the list of Companies will look as follows:

http[s]://deepserhost/api/rest/companies

where:

• http[s]://deepserhost/api/rest is the endpoint
• /companies is the action URL

UNDERSTANDING ROUTES

Typically, Deepser has 2 main routes for each entity’s action URL.
The first one, we have just seen, is used to retrieve the entity collection, so it is generally the name of the entity in a plural form. For the entity Company it is:

http[s]://deepserhost/api/rest/companies

It must be called using an HTTP GET request and can be followed by filters or parameters (described in the next chapters) to provide the desired selection of the records.
For example, if we want to retrieve only the first Company with name starting with ‘ACME’, we should use this HTTP request to the REST API:

http[s]://deepserhost/api/rest/companies?filter[1][attribute]=name&filter[1][like]=ACME%&limit=1

We will explain in the next chapters all the filters and parameters.
To analyze this simple request, we have defined (after the endpoint and the route):

• filter: an array containing in each element the structure of the filter
• [attribute]: the element of each filter with the attribute to filter
• [like]: the element of each filter with the selection type (in our case we want a SQL like)
• limit: a parameter to limit the response results to just one element

If we want to retrieve a single element (eg: for which we already know the ID) we don’t use the routes to access a collection, but we use the route to get the single entity.
This is typically the name of the entity, followed by the ID of the entity.
In our example we get the company with ID = 4

http[s]://deepserhost/api/rest/company/4

It will retrieve all fields of the company with ID = 4.