Changelog

Retrieving objects

Suggest Edits

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 optimally a namespace query parameter if the identifier is an external one. In addition, there are additional a couple of query parameters to 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. If the domain specification is well linked to other domain specifications and/or contains many nested properties, then the retrieval operation might require more time. In certain cases it could also lead to a timeout if the number of nested properties are too large.

In such case, it is more efficient to retrieve only the first or second hop of properties for an identifier and afterwards retrieve additional objects.

Another option is to use so called projection domain specifications which specify what properties are relevant and should be retrieved.

Relevant API parameters for the optimisation

  • Header parameter X-HOP: integer to define to which depth the properties of an identifier should be retrieved ( we recommend to set it to 2)
  • ?projectionDs=URI query parameter to specify the projectionDS

Example calls

Retrieving an object with an internal identifier

If we want to retrieve our first running example, then we just need to call the API with the localname 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 which uses an external identifier, then we need to call the APi with the localname and namespace query parameter.

For example, the localbusiness running example object has the external identifer http://example.com/entity/LB1 with the localname 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 see also 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 set of properties that should be returned for a given object is to use a so called projection domain specification (projection DS).

A domain specification can be used as a projection DS and the system will return only the properties that are 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 returns the properties as defined in https://semantify.it/ds/Xkd5YH3-1for a given id as follow:

curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v1/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 6 months ago