Best Practices
This document lists general best practices when using the REST API of an ADOXX-based product. It focuses especially on how to maximize performance when using the search endpoints.
Keeping the result data set small
A request should generally be focused to retrieve only the data necessary for the current use case. Most endpoints provide parameters to modify the amount of retrieved data. This can improve the performance of the call due to smaller amounts of fetched data and will in some cases also skip certain parts of the computation, further speeding up the response.
Example: Omission of HATEOAS links
The data returned by several endpoints contains HATEOAS links. If these links are not needed, they can for most endpoints be deactivated by passing 'rest_links=true' in a request's Prefer header.
Example: Explicit specification of attributes and/or relations to be fetched
For requests that return model or object data the attributes and/or relations that are returned can be specified. By default, all attributes and relations will be returned, often resulting in a large response size. It is recommended to explicitly specify which attributes and relations to include in the response using the attribute and relation parameters. To include multiple attributes and/or relations, pass the attribute and/or relation parameters multiple times.
Relevant endpoints are contained in:
Optimizing search performance
As search requests can return large amounts of found entries and each found entry itself can contain multiple attributes and relations, it is highly recommended to formulate search requests as specific as possible and follow certain guidelines to ensure performance and stable behavior.
Use filters and scope to keep the data set as small as possible
For search queries and search jobs, the filters and scope properties should be used to specify the desired result as detailed as possible (see Queries).
Usage of big data mode
Big data mode is an internal mode that can be activated for the Search and Search Job endpoints (see Queries for details). It is recommended to always set this to true to ensure efficient processing of a search query.
Usage of paging
Search requests can result in thousands of found entries. Compiling and transporting such large amounts of data will stress the server and the network. It is therefore required to retrieve search results in multiple pages, utilizing a sensible page size. The page size of search results can be specified using the parameters range-start and range-end. The default page size when retrieving search results is 1000, bigger page sizes should never be used in production scenarios.
Usage of search jobs
A search executed using the Search endpoint will find data according to the specified query and return the first page of the result. For fetching additional pages, the endpoint will have to be called again, resulting in repeating the internal search call. For search requests that return large amounts of data fetched in multiple pages, it is recommended to create a Search Job. This will execute the search and store the result so it can be faster fetched.
Search jobs will automatically be deleted after one hour, but should always be explicitly removed when all the necessary data was fetched.
Explicit specification of attributes and/or relations to be fetched
For search results, the attributes and/or relations that should be fetched should explicitly be specified. For search queries and search jobs, the attributes and relations can be specified in the query object (see Queries). Note that if no specific attributes array is passed in a search query or an empty attributes array is passed, all attributes will be retrieved. Note that if an empty relations array is passed in a search query, all relations will be retrieved.
For saved search queries, the contained attributes can be specified using the attribute parameters, the contained relations can be specified using the relation parameter.
Omission of irrelevant data
The omit-property parameter should be used to omit parts of the data that might not be needed in certain scenarios, e.g. detailed links, release workflow-related information, etc. This option should be used to reduce the result sizes as much as possible.
For search queries and search jobs, properties such as omitRecords, omitBrokenRelations, etc. (see Queries) should be used to further reduce the result sizes.