Retrieving objects
The read-API retrieves the data for a given ID from the knowledge graph.
The API expects the local name of the identifier as a path parameter and optionally a namespace query parameter if the identifier is external. In addition, a couple of query parameters specify what should be returned.
Optimisations: X-Hop and iterative loading of nested objects
The retrieval operation, by default, identifies the domain specification with which the object was inserted and then builds a query to retrieve all properties in such domain specification. The retrieval operation might require more time if the domain specification is well-linked to other domain specifications and/or contains many nested properties. In certain cases, it could also lead to a timeout if the number of nested properties is too large.
In such a case, retrieving only the first or second hop of properties for an identifier and retrieving additional objects is more efficient. An additional option is to use projection domain specifications that specify what properties are relevant and should be retrieved.
If the query still times out or takes too long, the reason might be that the number of "types" (Domain Specifications) is too big. In this case, the API allows the specification of a DS list, which acts as a filter for the query. This decreases the response time dramatically.
Relevant API parameters for the optimisation
X-HOP: integer
Header parameter, to define to which depth the properties of an identifier should be retrieved ( we recommend setting it to 2 or lower)projectionDs=URI
query parameter to specify the projection DS, for example, https://semantify.it/ds/Xkd5YH3-1
Example calls
Retrieving an object with an internal identifier
If we want to retrieve our first running example, we need to call the API with the local name of the identifier in the returned Import Report.
curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v1/kg/things/$LOCAL_NAME' \
--header 'X-PUBLISHER: $PUBLISHER_UUID' \
--header 'Content-Type: application/ld+json' \
--header 'X-DATASOURCE: $DATASOURCE_UUID' \
--header 'x-api-key: $API_KEY'
You should see a response similar to the one below:
[
{
"@id": "http://onlim.com/entity/$LOCAL_NAME",
"@type": [
"https://schema.org/Event"
],
"https://schema.org/description": [
{
"@value": "This is the running example event description"
}
],
"https://schema.org/name": [
{
"@value": "Running example"
}
],
"https://schema.org/startDate": [
{
"@type": "http://www.w3.org/2001/XMLSchema#dateTime",
"@value": "2023-05-16T18:00:00+02:00"
}
],
"https://schema.org/url": [
{
"@type": "http://www.w3.org/2001/XMLSchema#anyURI",
"@value": "http://example.com/exampleEvent"
}
]
}
]
Retrieving objects based on an external identifier
If we want to retrieve objects that use an external identifier, we need to call the APi with the local name and namespace query parameter.
For example, the local business running the example object has the external identifier http://example.com/entity/LB1 with the local name LB1
and the namespace http://example.com/entity/
curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v1/kg/things/LB1?ns=http://example.com/entity/' \
--header 'Content-Type: application/ld+json' \
--header 'x-api-key: $API_KEY'
Which leads to the following response
[
{
"@id": "http://example.com/entity/LB1",
"@type": "https://schema.org/LocalBusiness",
"https://schema.org/address": {
"@id": "http://onlim.com/entity/2e50523d-bf7d-4998-9a18-8538f8a12ac6",
"@type": "https://schema.org/PostalAddress",
"https://schema.org/addressCountry": "DE",
"https://schema.org/addressLocality": "city",
"https://schema.org/postalCode": "1234",
"https://schema.org/streetAddress": "example street",
"https://vocab.sti2.at/ds/compliesWith": {
"@id": "https://semantify.it/ds/NP8df6sKy"
}
},
"https://schema.org/description": "A simple description about the local business",
"https://schema.org/name": "LocalBusinessTest",
"https://vocab.sti2.at/ds/compliesWith": {
"@id": "https://semantify.it/ds/uGBhB9lBI"
}
}
]
We also see in the response that the address object has an internal identifier http://onlim.com/entity/2e50523d-bf7d-4998-9a18-8538f8a12ac6
Retrieving partial data of an object
In certain use cases, one needs only a subset of all properties available for an object.
Retrieve only property value pairs that are x-hops from the root object away
For example, one is only interested in the direct properties of an object. To do so, the API provides the header flag X-HOP which allows the client to define the depth of the properties to be returned for a given object.
The following call would only return the direct properties and their values for a given object LB1 of our running example.
curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v1/kg/things/LB1?ns=http://example.com/entity/' \
--header 'Content-Type: application/ld+json' \
--header 'X-HOP: 1' \
--header 'x-api-key: $API_KEY'
Retrieving the details of an object within a projection Domain Specification
Another option to define the properties that should be returned for a given object is to use a projection domain specification (projection DS).
A domain specification can be used as a projection DS and the system will return only the properties defined in the respective DS.
For example, a defined projection DS is https://semantify.it/ds/Xkd5YH3-1.
The client can request that the system return the properties as defined in https://semantify.it/ds/Xkd5YH3-1for a given ID as follows:
curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v2/kg/things/LB1?ns=http://example.com/entity/&projectionDs=https://semantify.it/ds/Xkd5YH3-1' \
--header 'Content-Type: application/ld+json' \
--header 'x-api-key: $API_KEY'
Updated 5 months ago