Introduction to API
Deepser was designed to meet all IT department needs.
The Deepser REST API was designed to meet specific needs for the customization and integration of the software, in particular:
- Retrieve, store and process data in the best way for your organization
- Interface and integrate Deepser with third party applications
API REST is natively supported by any version of Deepser.
Before you start reading the guide it is important to know some key concepts, described in this chapter.
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: (deepdeskhost is your domain)
- To access the API you have to call the endpoint at: http[s]://deepdeskhost/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.
If you want to use the API you must authenticate before using it.
See this chapter for detailed instructions regarding the authentication.
As we will see below, the actions allowed to users are different, based on:
- Role of the user logged-in: an admin can create certain entities, while an end user can’t.
- Permissions of the user logged-in: a user who can access certain records is generally not allowed to see other users’ records.
- Entity: depending on the entity requested the permissions and the methods allowed can vary. For example, the Service Type entity can be only retrieved via API. To create a new Service Type an Administrator has to log in to Deepser web portal.
The REST API response is a JSON object, depending on the resource requested.
A brief example (we will describe in the next chapters in details) is the following:
“name”: “ACME International”,
“description”: “ACME International – Main Company of the group”,
“address”: “Madison Square Garden”,
“updated_at”: “2018-07-12 08:43:13”,
“created_at”: “2018-06-19 13:30:41”
“name”: “ACME France”,
“description”: “ACME France”,
“address”: “Roux de Strasse”,
“updated_at”: “2018-07-12 08:43:56”,
“created_at”: “2018-06-19 13:33:57”
HTTP verbs are used to manage the state of resources.
In Deepser REST API there are four verbs used to manage resources: GET, POST, PUT, and DELETE.
- get the contents of the data using HTTP GET
- delete the data using HTTP DELETE
- create or update the data using HTTP POST/PUT
Deepser API uses those methods to get, create, update or delete entities.
Based on the entity, on the role and the permissions of the logged-in user, there are different actions allowed.
The details will be explained in the next chapters, but you must remember the actions implemented by the API are:
- Retrieve: to get a single resource (HTTP GET)
- Create: to create a single resource (HTTP POST)
- Update: to update a single resource (HTTP PUT)
- Delete: to delete a single resource (HTTP DELETE)
- Multiple Retrieve: to get multiple resources (HTTP GET)
- Multiple Create: to create multiple resources (HTTP POST)
- Multiple Update: : to update multiple resources (HTTP PUT)
Multiple Delete is not allowed for Security Reasons.
All URLs in REST API have the following base URL.
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]://deepdeskhost/api/rest is the endpoint
- /companies is the action URL
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:
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:
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
It will retrieve all fields of the company with ID = 4.
Now that we have learnt the basics to access Deepser API, we want to understand how to authenticate to Deepser via API and raise a first request to the API.
Then, we will see all the entities accessible through Deepser API and the details to retrieve (get), create, update and delete data.