Retrieving objects

The read-API retrieves the data for a given ID from the knowledge graph.

The API expects the identifier's local name 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.

Explanation: identifier, local name and namespace

According to the Linked Data Principles, entity identification in a Knowledge Graph happens by IRIs. An IRI, for simplification, also called an identifier, looks like a normal URL and consists of a namespaces and a local name. The namespace is the part starting with http and ending with a / character. the local name is what comes behind the last /character.

Examples 1: IRI:

https://mein.toubiz.de/api/v1/event/fca3252e-23ea-4086-b07a-31bc2fa69aca

Namespace: https://mein.toubiz.de/api/v1/event/
Local name: fca3252e-23ea-4086-b07a-31bc2fa69aca

Examples 2: IRI:

https://www.bremen.de/bremer-stadtmusikanten?id=17211_extracted

Namespace: https://www.bremen.de/
Local name: bremer-stadtmusikanten%3Fid%3D17211

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 'https://proxy.opendatagermany.io/api/ts/v1/kg/things/0f327251-0931-415f-aa4c-6d44e9324403' \
-H 'Content-Type: application/ld+json' \
-H 'x-api-key: <APIKEY>'

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 using the local name and namespace query parameter.

For example, the local business running the example object has the external identifier https://mein.toubiz.de/api/v1/event/fca3252e-23ea-4086-b07a-31bc2fa69aca> with the local name fca3252e-23ea-4086-b07a-31bc2fa69acaand the namespace <https://mein.toubiz.de/api/v1/event/>

curl 'https://proxy.opendatagermany.io/api/ts/v1/kg/things/fca3252e-23ea-4086-b07a-31bc2fa69aca?ns=https://mein.toubiz.de/api/v1/event/' \
-H 'Content-Type: application/ld+json' \
-H 'x-api-key: <APIKEY>'

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 may only be interested in an object's direct properties. 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.

In the following example, the call would only return the direct properties and their values for a given object because of the x-hop: 1 specification.

curl 'https://proxy.opendatagermany.io/api/ts/v2/kg/things/020968973575-nxbz?ns=https://thuecat.org/resources/' \
-H 'accept: application/json' \
-H 'x-hop: 1' \
-H 'x-api-key: <APIKEY>'

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 'https://proxy.opendatagermany.io/api/ts/v2/kg/things/020968973575-nxbz?ns=https://thuecat.org/resources/&projectionDs=https://semantify.it/ds/Xkd5YH3-1' \
-H 'accept: application/json' \
-H 'x-api-key: <APIKEY>'