Introduction
Welcome to SD Elements API v2! Our API provides RESTful HTTP access to a large part of the functionality of SD Elements.
API Format
API results are currently returned in XML and JSON formats. It is advised to use the JSON format only. Specify the JSON format by including the HTTP header in all requests:
Content-type: application/json
Include Parameters
Some endpoints allow users to include extra fields in the response the API returns. This is used to add a specific field to an element, or collection of elements. For example, we may wish to receive a collection of projects that are within an application. Since projects are normally not a field of the applications resource, we can include projects in our request to see the projects as an additional field.
/?include={field_to_include}
Exclude Parameters
Some endpoints allow users to exclude fields in the response the API returns. This is used to remove a specific field from an element, or collection of elements. For example, we may wish to exclude the list of members in a collection of projects. Since members are normally a field of the project resource, we can exclude members in our request to remove it from the response. Excluding unnecessary fields can improve the performance of an endpoint.
/?exclude={field_to_exclude}
Expand Parameters
Some endpoints allow users to expand a field that is already present in the response. For example, by default, an application element contains the id of the business unit to which it belongs. If we wish to retrieve more information about the business unit, we would expand the business unit field to get more information.
/?expand={field_to_expand}
It is possible to include and expand more than one field simultaneously:
/?include={field1},{field2}&expand={field3},{field4}
Custom Filtering Lookups
Some endpoints allow users to perform custom lookups on a field. Not all fields support all lookups, so it is best to refer to individual endpoints to see exactly what is supported.
Below is a list of the different lookups that some fields may support.
| Lookup | Description | Example Usage |
|---|---|---|
| iexact= | case insensitive exact match | ?field__iexact={value} |
| contains= | string contains | ?field__contains={value} |
| icontains= | case insensitive string contains | ?field__icontains={value} |
| in= | multiple values | ?field__in={value1},{value2},{value3} |
| lte= | less than or equal | ?field__lte={value} |
| lt= | less than | ?field__lt={value} |
| gte= | greater than or equal | ?field__gte={value} |
| gt= | greater than | ?field__gt={value} |
| range= | range including lower and upper bound | ?field__range={lower_bound},{upper_bound} |
For example, if the field to be filtered is name, a custom lookup query would look like this:
/?name__icontains={value}
Pagination
Consume long responses by enabling pagination on an endpoint. Specify a page size in the URL (this example sets a page size of 10):
/?page_size=10
This will limit the result set down to 10 (or fewer) elements. There will be a few additional values returned in addtion to the results list. next and previous are URLs you can request to get the next or previous result set. count is the total number of resources available.