* Article is under review *
This article assumes you have checked the introduction article. If not, please do so first.
Retrieving data introduction
To retrieve data from the REST API, you need to use a GET request. To retrieve all objects of a type, you can retrieve the object without an ID. However, to retrieve a specific object for a type, you need to specify the object ID in the request.
Example call without ID: HTTPS GET https://lynx.a-dato.com/api/projects
Example call with ID: HTTPS GET https://lynx.a-dato.com/api/projects/123
In the first example, you are retrieving all projects in your space. However, in the second example, you specify that you want to retrieve the project with ID "123" from your space.
Some objects are children objects of other objects. For instance, a task is a child of a project and a card is a child of a task. Therefore, to retrieve a certain task, you need to add the parent object to the get request call.
Example tasks: HTTPS GET https://lynx.a-dato.com/api/projects/123/tasks
Example cards: HTTPS GET https://lynx.a-dato.com/api/projects/123/tasks/123/cards
In the first example, you are retrieving the task by specifying which project ID you are referring to, and specifying that you want all task objects of the project. In the second example, you are retrieving all of the cards of a specific task (ID: 123) in a specific project (123).
The hierarchy needs to be included in the correct order, for example, you cannot specify the task ID first, then the project ID as the project is the parent of the task.
Filtering
We have included an option to filtering the retrieved data. This will only show those fields of the objects, so you can select which data you want to see.
For filtering, it is good to know which properties an object has. The schema of the Swagger documentation shows the properties of all objects.
There are two kinds of filtering that can be added to a GET request's query parameter:
- "Query" parameter: Filters which data is shown in the response.
- "Field" parameter: Filters which fields are shown in the response.
"Query" parameter
To filter the data, you can add a "query" query parameter in the GET request to specify what value a certain field should have. The filters need to be URL encoded to work.
Example call: HTTPS GET https://lynx.a-dato.com/api/projects/123/tasks?query=TaskManagers.FirstName.Contains%28%22John%22%29
In this example, we are retrieving tasks in project with ID "123", but specifically only the tasks who has a task manager with a first name "John". The filter is URL encoded which can be generated online, for example from this webiste: urlencoder.org.
"Filter" parameter
To filter the fields of the object to retrieve, you can add a "field" query parameter. Examples of fields to filter on are ID, Description, TaskManagers.FirstName, and TaskManagers.LastName.
Example call: https://lynx.a-dato.com/api/projects/123/tasks?fields=ID
In this example, the project with ID "123" will be shown with only the ID field in the object structure.
More information
- You can combine the "query" and "field" parameter to filter the data on certain values and only show certain fields.
- You need to use 'or' and 'and' for separating multiple queries.
- The queries currently support: '=', '!=', '<', '>', '<=', '>=' or '{propertyName}.Contains("value")'.
Comments
0 comments
Please sign in to leave a comment.