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 LB1and 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'