Changelog

Optimisations

Suggest Edits

The query performance (response times) depends on the shape and amount of query-relevant data.

For example, a domain specification with many optional properties and/or deep nested elements requires a more expensive query, which might result in more query-relevant data. In contrast, a query that should only return the name of an object will be considerably faster.

Also, large page sizes will increase the response time of the operation. Additionally, the number of different types (domain specifications) in a result set can notably increase the response time.

Some use cases require a more sophisticated interaction with the APIs.

🚧

V1 is deprecated, please use V2

Version 1 of this endpoint is deprecated, please use V2. The difference in calling the API is minor (the /v1 needs to be replaced with /v2). The changes in the response concern the quantity and nesting-depth of the properties. While V1 was responding with all properties of an object, V2 will only respond with the @id, @type and ds:compliesWith property. The actual data lookup needs to happen in a second step over the endpoint to retrieve an entity by id: https://changelog-dzt-kg.readme.io/reference/getthingbyid.

Note: since the API's introduction of V2, the most relevant optimization is the filtering for given Domain specifications.

Reduce the page size for pagination

A smaller page size (e.g. 5) will reduce the data retrieved for one call and the query and response times.

This can be achieved by using the HTTP header parameter page-size: integer and further page: integer to navigate the pages.

Restrict the number of hops for the attributes that are returned

One can use the HTTP header parameter X-HOP to define the depth of information returned for an object.
For example,

  • a value of X-HOP:0 would return only the ids, their domain specification and their type
  • a value of X-HOP:1 would return only the ids, their domain specification and their type and all outgoing property-value pairs for each result.
  • By specifying X-HOP:2 the response would contain a property path of length 2.

Afterwards, one can request the information of nested objects.

Filter for given Domain Specifications

To increase the performance of a retrieval call, there is the option to specify a filter DS list. This filter will only retrieve objects which comply with a DS from a given DS list.

This can be achieved by using the URL parameter filterDsList=URI to specify a filter DS list, for example, https://semantify.it/list/LRVOilZZ6.

Example

curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v2/kg/things/?doTypeCount=false&filterDsList=https%3A%2F%2Fsemantify.it%2Flist%2FLRVOilZZ6' \
--header 'content-type: application/ld+json' \
--header 'x-api-key: $API_KEY'

Updated 5 months ago