Metadata REST/API

For the integration or exchange of metadata with other applications, REST interfaces are provided, allowing direct read and write access to individual metadata objects.

Note

In the following examples, the database test and the server https://www.myserver.com are used for illustration purposes (e.g. in the path https://www.myserver.com/rest/test/schemes). This database or server must be replaced accordingly in all actual requests. Depending on the configuration, the URL may also have to be extended by the context path (e.g. https://www.myserver.com/dataspot/rest/test/schemes).

The dataspot REST/API is a programming interface that provides direct read and write access to individual metadata objects over HTTP.

The structures and properties are based on the dataspot metamodel.
The metadata is provided in JSON format.

Metamodel

The metamodel documents all properties and relationships of metadata objects and provides the foundation for all REST/API requests. The metamodel is available in the database meta at the following URL:

https://www.myserver.com/web/meta

Note

The database meta can be created in the admin console (https://www.myserver.com/web/admin).

OpenAPI Specification

The OpenAPI Specification of the REST/API (including all paths, parameters, and structures) can be accessed at the following URL:

https://www.myserver.com/specification/openapi.yaml
https://www.myserver.com/specification/openapi.json

Technical principles

The REST/API is implemented according to the REST software architecture paradigm.

Note

The REST/API requires appropriate login credentials. Depending on the authentication method (Login ID and password, Single sign-on, Same sign-in, OpenID Connect) and used tools (e.g. curl), different mechanisms (e.g. basic authentication, bearer token) may be necessary to provide the credentials.

The user must have sufficient authorization, in particular for requests that change data.

The REST/API follows the basic design principle HATEOAS, which allows the caller of a REST interface to navigate almost exclusively through URLs provided by the server (and thus included in the response). HATEOAS is implemented using JSON Hypertext Application Language (HAL) (see also IETF Internet-Draft).

HTTP methods

Depending on the endpoint, the REST/API supports the following HTTP methods.

Note

If a proxy server or a reverse proxy is deployed, the respective HTTP methods (GET, POST, PUT, PATCH, DELETE) may not be rejected.

POST

POST creates a new metadata object:

The technical key or business key of the metadata object is coded in the URL.
The request payload contains the new metadata object.
The response payload contains the created metadata object.

# Create new collection
POST /rest/test/schemes/Business Data Model/collections

GET

GET queries an existing metadata object:

The technical key or business key of the metadata object is coded in the URL.
The response payload contains the queried metadata object.

# Query collection 'Human Resources'
GET /rest/test/schemes/Business Data Model/collections/Human Resources

GET queries an existing list of metadata objects:

The technical key or business key of the list of metadata objects is coded in the URL.
The response payload contains the queried list of metadata objects.

# Query list of enumerations
GET /rest/test/schemes/Referenzdaten/enumerations

# Query list of responsibilities
GET /rest/test/schemes/Business Data Model/attributedTo

PUT

PUT updates an existing metadata object:

The technical key or business key of the metadata object is coded in the URL.
The request payload contains the update of the metadata object.
- The specified properties are updated.
- The remaining properties are deleted, i.e. the existing metadata object is completely replaced.
- In case the metadata object doesn't exist yet, it is created.
The response payload contains the updated metadata object.

# Update collection 'Human Resources'
PUT /rest/test/schemes/Business Data Model/collections/Human Resources

PUT updates an existing list of metadata objects:

The technical key or business key of the list of metadata objects is coded in the URL.
The request payload contains the update of the list of metadata objects.
- Every existing metadata object, that occurs in the list, is updated.
  - The specified properties are updated.
  - The remaining properties are deleted, i.e. the existing metadata object is completely replaced.
  - In case a metadata object in the list doesn't exist yet, it is created.
- Every existing metadata object, that doesn't occur in the list, is deleted.
The response payload contains the updated list of metadata objects.

# Update list of enumerations
PUT /rest/test/schemes/Referenzdaten/enumerations

PATCH

PATCH modifies an existing metadata object:

The technical key or business key of the metadata object is coded in the URL.
The request payload contains the modification of the metadata object.
- The specified properties are modified.
- The remaining properties remain unchanged, i.e. the existing metadata object is not completely replaced.
- In case the metadata object doesn't exist yet, it is created.
The response payload contains the modified metadata object.

# Modify collection 'Human Resources'
PATCH /rest/test/schemes/Business Data Model/collections/Human Resources

PATCH modifies an existing list of metadata objects:

The technical key or business key of the list of metadata objects is coded in the URL.
The request payload contains the modification of the list of metadata objects.
- Every existing metadata object, that occurs in the list, is modified.
  - The specified properties are modified.
  - The remaining properties remain unchanged, i.e. the existing metadata object is not completely replaced.
  - In case a metadata object in the list doesn't exist yet, it is created.
- Every existing metadata object, that doesn't occur in the list, is deleted, if the query parameter operation=REPLACE is set (otherwise, the obsolete metadata objects are not deleted).
The response payload contains the modified list of metadata objects.

# Modify list of enumerations (keep obsolete enumerations)
PATCH /rest/test/schemes/Referenzdaten/enumerations

# Modify list of enumerations (remove obsolete enumerations)
PATCH /rest/test/schemes/Referenzdaten/enumerations?operation=REPLACE

DELETE

DELETE removes an existing metadata object:

The technical key or business key of the metadata object is coded in the URL.
There is neither a request payload nor a response payload.

# Remove collection 'Human Resources'
DELETE /rest/test/schemes/Business Data Model/collections/Human Resources

DELETE removes an existing list of metadata objects:

The technical key or business key of the list of metadata objects is coded in the URL.
There is neither a request payload nor a response payload.

# Remove list of enumerations
DELETE /rest/test/schemes/Referenzdaten/enumerations

Technical key

The REST/API allows metadata objects to be referenced by their UUID (Universally Unique Identifier):

The UUID uniquely identifies each metadata object (globally and across systems).
Metadata objects are accessed by their UUID using the path corresponding to their metadata object type.
- For example, an Attribute identified by <uuid> is accessed using the path /rest/attributes/<uuid>.

GET    /rest/test/attributes/1078f122-73a0-4996-90ed-ab4b7d6c0a9d
PUT    /rest/test/classifiers/9759a2a2-3d55-4517-bf21-323d823d8fff
PATCH  /rest/test/groups/fdd37002-f8b2-40d6-8832-80d1508944ca
DELETE /rest/test/attributes/0f125f21-f828-400a-a624-bdb26cf27806

Note

Metadata objects can be accessed by their UUID even if the concrete metadata object type is unknown. Following the hierarchy defined in the metamodel, more general paths can also be used. For example, a Processing is a subtype of Activity and a Activity is a subtype of Asset (according to the metamodel). Therefore, a Processing identified by <uuid> can be accessed not only using the path /rest/processings/<uuid> but also using the more general paths /rest/activities/<uuid> or /rest/assets/<uuid>.

Business key

The REST/API allows metadata objects to be referenced by their label:

The label uniquely identifies each metadata object within the object hierarchy, i.e. starting from a metadata object all subordinate metadata objects can be identified by their label.
These business keys can be assembled into a path, starting with the top level /schemes or /organizations and proceeding from there to all further subordinate metadata objects.

GET    /rest/test/schemes/Business Data Model
GET    /rest/test/schemes/Business Data Model/attributedTo
GET    /rest/test/schemes/Business Data Model/classifiers/Country
GET    /rest/test/schemes/Business Data Model/classifiers/Country/attributes/ISO Code
POST   /rest/test/schemes/Business Data Model/collections/Human Resources/classifiers
PUT    /rest/test/organizations/Organization/persons/Smith James
PATCH  /rest/test/organizations/Organization
DELETE /rest/test/schemes/Business Data Model/classifiers/Country/attributes/ISO Code

Format

The REST/API supports the transfer of data in JSON:

For read access, the REST/API returns metadata objects in JSON Hypertext Application Language format.
- The special property _type defines the metadata object type.
- The special property _links contains (in accordance with the design principle HATEOAS) all URLs that the caller of the REST interface can use for further navigation.
  - The property self contains the URL to the metadata object itself.
  - All relations of the metadata object to other (i.e. parent, child or otherwise related) metadata objects are specified in further properties within _links.
- The special property _embedded contains (for queries that return lists) the list of the corresponding metadata objects.
For write access, the REST/API accepts metadata objects in JSON format (without special JSON/HAL properties).
- The special property _type defines the metadata object type.

Example: Query a single attribute

Request:
  GET /rest/test/schemes/Business Data Model/classifiers/Country/attributes/ISO Code

JSON/HAL Response-Payload:
  {
      "_type": "BusinessAttribute",
      "id": "fc918bc8-4380-4299-8b52-b42b8b1bc806",
      "_version": 1,
      "tenant": "e2e5d8b6-da70-4985-b795-9cce4f13ce95",
      "createdBy": "admin",
      "dateCreated": 1624621433852,
      "db": "test",
      "description": "Geographic unit (ISO 3166-1)",
      "label": "ISO Code",
      "modelId": "1078f122-73a0-4996-90ed-ab4b7d6c0a9d",
      "status": "WORKING",
      "title": "Country ISO code",
      "hasDomain": "c342ba91-86ea-42c9-9218-177505fbca6e",
      "hasRange": "1dfce9fa-9815-4b06-a322-43999c4f5aaf",
      "identifying": true,
      "maxCardinality": 1,
      "minCardinality": 0,
      "required": "OPTIONAL",
      "cardinality": "ONE",
      "parentId": "c342ba91-86ea-42c9-9218-177505fbca6e",
      "href": "/web/test/attributes/fc918bc8-4380-4299-8b52-b42b8b1bc806",
      "_links": {
          "self": {
              "href": "/rest/test/attributes/fc918bc8-4380-4299-8b52-b42b8b1bc806"
          },
          "derivedTo": {
              "href": "/rest/test/attributes/fc918bc8-4380-4299-8b52-b42b8b1bc806/derivedTo"
          },
          "hasDomain": {
              "href": "/rest/test/classifiers/c342ba91-86ea-42c9-9218-177505fbca6e"
          },
          "hasRange": {
              "href": "/rest/test/enumerations/1dfce9fa-9815-4b06-a322-43999c4f5aaf"
          }
      }
  }

Example: Query a list of responsibilities

Request:
  GET /rest/test/schemes/Referenzdaten/attributedTo

JSON/HAL Response-Payload:
  {
      "total": 2,
      "_links": {
          "self": {
              "href": "/rest/test/schemes/22d6d683-3d59-46c7-a355-594a426ea309/attributedTo"
          }
      },
      "_embedded": {
          "attributedTo": [
              {
                  "id": "18d33dc6-b8ab-4991-80de-f5e07567af8a",
                  "attributionFor": "22d6d683-3d59-46c7-a355-594a426ea309",
                  "attributedTo": "ecae0cba-b800-4086-9fb2-c051aa5064a7",
                  "_links": {
                      "self": {
                          "href": "/rest/test/attributions/18d33dc6-b8ab-4991-80de-f5e07567af8a"
                      }
                  }
              },
              {
                  "id": "4ed01578-300b-4b72-98cc-df1fe4ae7d79",
                  "attributionFor": "22d6d683-3d59-46c7-a355-594a426ea309",
                  "attributedTo": "7644bdc0-f1e1-4bf4-a85a-8a0e72822389",
                  "_links": {
                      "self": {
                          "href": "/rest/test/attributions/4ed01578-300b-4b72-98cc-df1fe4ae7d79"
                      }
                  }
              }
          ]
      }
  }

Example: Modify a single attribute

Request:
  PATCH /rest/test/schemes/Business Data Model/classifiers/Land/attributes/ISO Code

JSON Request-Payload:
  {
      "_type": "BusinessAttribute",
      "identifying": false
  }

Error handling

If any errors occur while processing the data in the interface, a corresponding error message is returned. Additionally, the HTTP status code of the HTTP response is set. The response contains the following properties:

statusCode: HTTP status code
method: HTTP method
message: Error message (description)
violations (optional): List of constraint violations
_links.self: URL of the erroneous request

Example: Query a model that does not exist

Request:
  GET /rest/test/schemes/Unknown

  JSON/HAL Response-Payload:
  {
      "statusCode": 404,
      "method": "GET",
      "message": "Scheme *Unknown* was not found!",
      "_links": {
          "self": "/dataspot/rest/test/schemes/Unknown"
      }
  }

Example: Create an invalid person

Request:
  POST /rest/test/persons

JSON Request-Payload:
  {
      "_type": "Person",
      "familyName": "Mayer"
  }

JSON/HAL Response-Payload:
  {
      "statusCode": 400,
      "method": "POST",
      "message": "Cannot create Person!",
      "violations": [
          {
              "message": "*Agent of* is mandatory!",
              "path": "agentOf"
          },
          {
              "message": "*Given name* is mandatory!",
              "path": "givenName"
          }
      ],
      "_links": {
          "self": "/dataspot/rest/test/persons"
      }
  }

Metamodel​

OpenAPI Specification​

Technical principles​

HTTP methods​

POST​

GET​

PUT​

PATCH​

DELETE​

Technical key​

Business key​

Format​

Error handling​

Metamodel

OpenAPI Specification

Technical principles

HTTP methods

POST

GET

PUT

PATCH

DELETE

Technical key

Business key

Format

Error handling