Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Note

This feature is only available for in the BiZZdesign cloud solution.


Excerpt
[BETA]


A data enrichment open API is available in the HoriZZon server. With this data enrichment API, external data and attributes can be added to existing structural data created by Enterprise Studio. In order to use the open API a named "API client" must be created in HoriZZon.

Example
headerRequired roles

Administrator or System Administrator


Excerpt

On this page:


Table of Contents
maxLevel1


Creating a named API client

The first step for using the API is creating an API Client. Every API Client has a unique identifier (the Client ID) and an associated secret key that can be used to request access tokens to authenticate with the API.

  1. In the sidebar menu, click Clients.

  2. Click Create API client.



  3. Set the API client properties. If you want to have the possibility to also write data into the API client, select Write permission. Click Create to create the client.



  4. When the API client is successfully created, a generated client secret is shown. This client secret is needed to connect your application to the BiZZdesign open API. Save a copy of the client secret somewhere in a safe place. After that, click Done.

    Once you leave the page, the client secret is gone.


Requesting an API Access Token

The generated API Client credentials can be used to create a temporary access token to authenticate your API calls. For authentication OAuth 2 is used, a modern standard for securing access to APIs. The token is created by sending a POST request to https://<orgname>.bizzdesign.cloud/oauth/token with the following parameters :


KeyValue
grant_typeclient_credentials
client_id<generated Client ID>
client_secret<generated secret>


Tip

The hostname for requesting API Access Tokens is the same hostname used in the Enterprise Studio clients


These parameters can either be set as query parameters in the URL or in the body using x-www-form-url encoded data. Possible return values are:


Response codeBodyDescription
200Access token in RFC 7519 format (JWT)Relevant attributes are access_token (which contains the token used to authenticate to the API) and expires_in (lifetime of the access token, in seconds). The access token uses the JSON Web Token format defined in RFC 7519. 
400JSON-formatted error messageInvalid request
401emptyThe combination of client_id and client_secret is invalid
403emptyYour current license level does not cover use of the Open API


Below is a simple example using Curl, assuming your HoriZZon environment is normally accessed via  https://<orgname>.horizzon.cloud/ .


Code Block
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CustomerClientID' \
--data-urlencode 'client_secret=CustomerClientSecret' \
https://<orgname>.bizzdesign.cloud/oauth/token

Anchor
Submitting requests to the Open API
Submitting requests to the Open API
Submitting requests to the Open API

Once a valid access token is obtained requests can be submitted to the Open API using the URL https://<orgname>-api.horizzon.cloud/api/<version>/<API-call>. During the OpenAPI beta the version identifier is "beta", so for example, if your HoriZZon environment is normally accessed via https://<orgname>.horizzon.cloud/, the API is reachable via  https://<orgname>-api.horizzon.cloud/api/beta/. 

Warning

The hostname used for OpenAPI requests is different from the hostname normally used to access HoriZZon, note the extra -api part in the name!


The access token is used as a bearer token, which means it should be sent in the Authorization: header, with the value of the header set to "Bearer <tokenvalue>". An example using Curl to request a list of all collaborations in JSON format:


Code Block
curl -H "Accept: application/json" \
-H "Authorization: Bearer ReplaceThisWithTheBearerTokenRetrievedInThePreviousStep" \
https://<orgname>-api.horizzon.cloud/api/beta/collaborations

Open API documentation

The following API calls are available for use:

Open API Documentation
showCommonExtensionstrue
deepLinkingtrue
supportedSubmitMethodsnone
showDownloadButtontrue
{
  "openapi": "3.0.1",
  "info": {
    "title": "BiZZdesign Data Enrichment API",
    "description": "API for enriching architectural elements managed by the <b>BiZZdesign toolset</b>.<br><br>BiZZdesign <b>Enterprise Studio</b> allows invited users to collaboratively model architectural structural objects, store these in BiZZdesign <b>Team Server</b>, and publish them to selected user groups on the <b>HoriZZon</b> platform. Part of this collaborative process is managing a set of properties for each modeled object. Property values are assigned in <b>Enterprise Studio</b>, and stored with the object in <b>Team Server</b>. <b>HoriZZon</b> will display their values with the object, but does not allow changing them.<br><br>On top of these read-only properties <b>HoriZZon</b> supports <i>data enrichment</i>: additional object attributes of which the values can be edited in <b>HoriZZon</b> itself. These attributes are defined in a <i>schema</i>, and their values are attached to an object in the form of a <i>document</i>. This API allows an authorized client application to directly create, modify and delete schemas and documents, enriching the architecture with additional data that is visible and editable in (and only in) <b>HoriZZon</b>.",
    "version": "0.1.0"
  },
  "tags": [
    {
      "name": "schema",
      "description": "A <i>schema</i> describes a group of attributes that can be instantiated (as a <i>document</i>) and then linked to an architectural entity (i.e. an <i>Enterprise Studio object</i>)."
    },
    {
      "name": "document",
      "description": "A <i>document</i> is a group of attribute values that conforms to a schema and is linked to an architectural entity (i.e. an <i>Enterprise Studio object</i>)."
    },
    {
      "name": "object",
      "description": "An <i>object</i> represents an architectural entity in a model package (i.e. an <i>Enterprise Studio object</i>)."
    },
    {
      "name": "collaboration",
      "description": "A <i>collaboration</i> is a Team Server entity that allows invited users to collaboratively model architectural structural data stored in a model package."
    }
  ],
  "paths": {
    "/api/collaborations": {
      "get": {
        "tags": [
          "collaboration"
        ],
        "summary": "Get all collaborations",
        "description": "Retrieve a list of all available collaborations.",
        "operationId": "getCollaborations",
        "parameters": [
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Pagination offset: the number of rows preceding the first row returned. When omitted, this number defaults to 0.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Pagination limit: number of rows to return. The maximum is 50. When omitted, this number defaults to 30.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The request was successful. The response body contains a JSON array of collaborations. This array might be empty.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Collaboration"
                  }
                },
                "example": [
                  {
                    "collaborationId": "repositories/1/collaborations/1",
                    "name": "Archisurance & portfolios",
                    "description": ""
                  },
                  {
                    "collaborationId": "repositories/2/collaborations/2",
                    "name": "The PiZZa collaboration",
                    "description": "BPMN example"
                  }
                ]
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          }
        }
      }
    },
    "/api/objects": {
      "get": {
        "tags": [
          "object"
        ],
        "summary": "Get all objects of a specified type",
        "description": "Retrieve a list of all Enterprise Studio objects of a certain type, located in the collaboration specified.",
        "operationId": "getObjects",
        "parameters": [
          {
            "name": "collaborationId",
            "in": "query",
            "required": true,
            "description": "The UUID that identifies the collaboration.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": true,
            "description": "The type of the objects to retrieve.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Pagination offset: number of rows preceding the first row returned. When omitted, this number defaults to 0.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Pagination limit: number of rows to return. The maximum is 50. When omitted, this number defaults to 30.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The request was successful. The response body is a JSON object, containing an array of objects (and some additional data). This array might be empty. Note that although documents associated with an object can be requested separately, they are returned also in this response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Object"
                  }
                },
                "example": {
                  "_items": [
                    {
                      "id": "9afe55ec-eb9b-e911-9c52-5065f34901c9",
                      "cluster": "7cfe55ec-eb9b-e911-9c52-5065f34901c9",
                      "class": "ArchiMate:BusinessActor",
                      "foundationClass": "object",
                      "model": "15fc55ec-eb9b-e911-9c52-5065f34901c9",
                      "name": {
                        "de": "Vorstand",
                        "en": "Board",
                        "nl": "Bestuur"
                      },
                      "parentId": "7cfe55ec-eb9b-e911-9c52-5065f34901c9",
                      "documents": []
                    },
                    {
                      "id": "98fe55ec-eb9b-e911-9c52-5065f34901c9",
                      "cluster": "7cfe55ec-eb9b-e911-9c52-5065f34901c9",
                      "class": "ArchiMate:BusinessActor",
                      "foundationClass": "object",
                      "model": "15fc55ec-eb9b-e911-9c52-5065f34901c9",
                      "name": {
                        "de": "Betriebsleiter",
                        "en": "Director of Operations",
                        "nl": "Operationeel directeur"
                      },
                      "parentId": "7cfe55ec-eb9b-e911-9c52-5065f34901c9",
                      "documents": [
                        {
                          "id": "52046945-53be-4552-b632-d855a13e9c90",
                          "schemaNamespace": "test",
                          "schemaName": "pizza",
                          "values": {
                            "vegetarian": true,
                            "orderNumber": 123,
                            "name": "Summer Special",
                            "topping": "pepperoni"
                          },
                          "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
                        }
                      ]
                    }
                  ],
                  "_offset": 0,
                  "_limit": 30,
                  "_count": 2
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          }
        }
      }
    },
    "/api/schemas": {
      "post": {
        "tags": [
          "schema"
        ],
        "summary": "Submit (a new version of) a JSON schema definition",
        "description": "When a schema with this namespace and name does not yet exist, it is added. When the schema already exists, this new definition will override the current version.<br><br>Existing documents using the previous definition will keep using this definition until written again, at which moment the new definition will be applied.",
        "operationId": "postSchema",
        "parameters": [
        ],
        "requestBody": {
          "description": "The JSON definition of the schema.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VersionedSchema"
              },
              "example": {
                "namespace": "test",
                "name": "pizza",
                "label": "Pizza Schema",
                "fields": [
                  {
                    "name": "vegetarian",
                    "label": "Vegetarian",
                    "schema": "boolean"
                  },
                  {
                    "name": "name",
                    "label": "Name",
                    "schema": "string"
                  },
                  {
                    "name": "orderNumber",
                    "label": "Order Number",
                    "schema": "long"
                  },
                  {
                    "name": "diameter",
                    "label": "Diameter",
                    "schema": "double"
                  },
                  {
                    "name": "cost",
                    "label": "Cost",
                    "schema": "money",
                    "constraints": {
                      "currency": "EUR"
                    }
                  },
                  {
                    "name": "date",
                    "label": "Order Date",
                    "schema": "date"
                  },
                  {
                    "name": "topping",
                    "label": "Topping",
                    "schema": "ingredient"
                  }
                ],
                "schemas": [
                  {
                    "kind": "enum",
                    "name": "ingredient",
                    "literals": [
                      {
                        "name": "pepperoni",
                        "label": "Pepperoni"
                      },
                      {
                        "name": "salami",
                        "label": "Salami"
                      },
                      {
                        "name": "pineapple",
                        "label": "Pineapple"
                      }
                    ]
                  }
                ],
                "types": [
                  "ArchiMate:BusinessActor"
                ],
                "publishedForRepository": 1
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The request was successful. The response body contains the JSON schema definition that was uploaded, complemented with some additional operational data (like a creation timestamp).",
            "content": {
              "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/VersionedSchema"
                },
                "example": {
                  "namespace": "test",
                  "name": "pizza",
                  "label": "Pizza Schema",
                  "fields": [
                    {
                      "name": "vegetarian",
                      "label": "Vegetarian",
                      "schema": "boolean",
                      "constraints": {}
                    },
                    {
                      "name": "name",
                      "label": "Name",
                      "schema": "string",
                      "constraints": {}
                    },
                    {
                      "name": "orderNumber",
                      "label": "Order Number",
                      "schema": "long",
                      "constraints": {}
                    },
                    {
                      "name": "diameter",
                      "label": "Diameter",
                      "schema": "double",
                      "constraints": {}
                    },
                    {
                      "name": "cost",
                      "label": "Cost",
                      "schema": "money",
                      "constraints": {
                        "currency": "EUR"
                      }
                    },
                    {
                      "name": "date",
                      "label": "Order Date",
                      "schema": "date",
                      "constraints": {}
                    },
                    {
                      "name": "topping",
                      "label": "Topping",
                      "schema": "ingredient",
                      "constraints": {}
                    }
                  ],
                  "schemas": [
                    {
                      "kind": "enum",
                      "name": "ingredient",
                      "literals": [
                        {
                          "name": "pepperoni",
                          "label": "Pepperoni"
                        },
                        {
                          "name": "salami",
                          "label": "Salami"
                        },
                        {
                          "name": "pineapple",
                          "label": "Pineapple"
                        }
                      ]
                    }
                  ],
                  "createdAt": 1557923108422,
                  "updatedAt": 1557923108422,
                  "types": [
                    "ArchiMate:BusinessActor"
                  ],
                  "publishedForRepository": 1,
                  "_links": {
                    "self": "/di/schemas/test/pizza"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          }
        }
      },
      "get": {
        "tags": [
          "schema"
        ],
        "summary": "Get all schemas",
        "description": "Retrieve a list of all available schema definitions.",
        "operationId": "getSchemas",
        "parameters": [
        ],
        "responses": {
          "200": {
            "description": "The request was successful. The response body is a JSON object containing an array of schema definitions. This array might be empty.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/VersionedSchema"
                  }
                },
                "example": {
                  "_items": [
                    {
                      "namespace": "test",
                      "name": "pizza",
                      "label": "Pizza Schema",
                      "fields": [
                        {
                          "name": "vegetarian",
                          "label": "Vegetarian",
                          "schema": "boolean",
                          "constraints": {}
                        },
                        {
                          "name": "name",
                          "label": "Name",
                          "schema": "string",
                          "constraints": {}
                        },
                        {
                          "name": "orderNumber",
                          "label": "Order Number",
                          "schema": "long",
                          "constraints": {}
                        },
                        {
                          "name": "diameter",
                          "label": "Diameter",
                          "schema": "double",
                          "constraints": {}
                        },
                        {
                          "name": "cost",
                          "label": "Cost",
                          "schema": "money",
                          "constraints": {
                            "currency": "EUR"
                          }
                        },
                        {
                          "name": "date",
                          "label": "Order Date",
                          "schema": "date",
                          "constraints": {}
                        },
                        {
                          "name": "topping",
                          "label": "Topping",
                          "schema": "ingredient",
                          "constraints": {}
                        }
                      ],
                      "schemas": [
                        {
                          "kind": "enum",
                          "name": "ingredient",
                          "literals": [
                            {
                              "name": "pepperoni",
                              "label": "Pepperoni"
                            },
                            {
                              "name": "salami",
                              "label": "Salami"
                            },
                            {
                              "name": "pineapple",
                              "label": "Pineapple"
                            }
                          ]
                        }
                      ],
                      "createdAt": 1557923108422,
                      "updatedAt": 1557923108422,
                      "types": [
                        "ArchiMate:BusinessActor"
                      ],
                      "publishedForRepository": 1,
                      "_links": {
                        "self": "/di/schemas/test/pizza"
                      }
                    }
                  ],
                  "_offset": 0,
                  "_limit": 30,
                  "_links": {
                    "self": "/api/schemas?offset=0&limit=30"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          }
        }
      }
    },
    "/api/schemas/{namespace}/{name}": {
      "get": {
        "tags": [
          "schema"
        ],
        "summary": "Get schema with name",
        "description": "Retrieve the schema with the specified namespace and name.",
        "operationId": "getSchemaWithName",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "required": true,
            "description": "The namespace in which the schema is defined.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The name of the schema.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The request was successful. The response body contains a JSON object representing the schema definition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionedSchema"
                },
                "example": {
                  "namespace": "test",
                  "name": "pizza",
                  "label": "Pizza Schema",
                  "fields": [
                    {
                      "name": "vegetarian",
                      "label": "Vegetarian",
                      "schema": "boolean",
                      "constraints": {}
                    },
                    {
                      "name": "name",
                      "label": "Name",
                      "schema": "string",
                      "constraints": {}
                    },
                    {
                      "name": "orderNumber",
                      "label": "Order Number",
                      "schema": "long",
                      "constraints": {}
                    },
                    {
                      "name": "diameter",
                      "label": "Diameter",
                      "schema": "double",
                      "constraints": {}
                    },
                    {
                      "name": "cost",
                      "label": "Cost",
                      "schema": "money",
                      "constraints": {
                        "currency": "EUR"
                      }
                    },
                    {
                      "name": "date",
                      "label": "Order Date",
                      "schema": "date",
                      "constraints": {}
                    },
                    {
                      "name": "topping",
                      "label": "Topping",
                      "schema": "ingredient",
                      "constraints": {}
                    }
                  ],
                  "schemas": [
                    {
                      "kind": "enum",
                      "name": "ingredient",
                      "literals": [
                        {
                          "name": "pepperoni",
                          "label": "Pepperoni"
                        },
                        {
                          "name": "salami",
                          "label": "Salami"
                        },
                        {
                          "name": "pineapple",
                          "label": "Pineapple"
                        }
                      ]
                    }
                  ],
                  "createdAt": 1557923108422,
                  "updatedAt": 1557923108422,
                  "types": [
                    "ArchiMate:BusinessActor"
                  ],
                  "publishedForRepository": 1,
                  "_links": {
                    "self": "/di/schemas/test/pizza"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          },
          "404": {
            "description": "The request failed because no schema exists with this namespace and name."
          }
        }
      },
      "delete": {
        "tags": [
          "schema"
        ],
        "summary": "Delete schema with name",
        "description": "Delete the schema with the specified namespace and name.<br><br><b>Please note that this will also remove all documents that use this schema!</b>",
        "operationId": "deleteSchemaWithName",
        "parameters": [
          {
            "name": "namespace",
            "in": "path",
            "required": true,
            "description": "The namespace in which the schema is defined.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "description": "The name of the schema.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The request was successful."
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          },
          "404": {
            "description": "The request failed because no schema exists with this namespace and name."
          }
        }
      }
    },
    "/api/documents": {
      "post": {
        "tags": [
          "document"
        ],
        "summary": "Create a new document",
        "description": "Create a new document and associate it with an Enterprise Studio object.",
        "operationId": "postDocument",
        "parameters": [
        ],
        "requestBody": {
          "description": "The JSON contents of the new document: values for any or all of the attributes defined in the associated schema.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentCreate"
              },
              "example": {
                "id": null,
                "schemaNamespace": "test",
                "schemaName": "pizza",
                "values": {
                    "vegetarian": true,
                    "orderNumber": 123,
                    "name" : "Summer Special",
                    "topping" : "pineapple"
                },
                "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The request was successful. The response body contains the JSON document that was uploaded, complemented with the document's ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                },
                "example": {
                  "id": "52046945-53be-4552-b632-d855a13e9c90",
                  "schemaNamespace": "test",
                  "schemaName": "pizza",
                  "values": {
                      "vegetarian": true,
                      "orderNumber": 123,
                      "name" : "Summer Special",
                      "topping" : "pineapple"
                  },
                  "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          },
          "409": {
            "description": "The request failed because the object already has a document for the specified schema. The response body contains a JSON object specifying the Team Server error number 'H_409' and a URL to the associated online help page."
          }
        }
      }
    },
    "/api/documents/{id}": {
      "put": {
        "tags": [
          "document"
        ],
        "summary": "Replace an existing document",
        "description": "Replace an existing document associated with an Enterprise Studio object.<br><br>If the associated schema has been updated since the last time this document was written, this latest schema version will be applied.",
        "operationId": "putDocument",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The UUID that identifies the document.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The new (JSON) contents of the document, which will replace its current contents. The content must adhere to the latest version of the associated schema.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentUpdate"
              },
                "example": {
                  "id": "52046945-53be-4552-b632-d855a13e9c90",
                  "schemaNamespace": "test",
                  "schemaName": "pizza",
                  "values": {
                      "vegetarian": true,
                      "orderNumber": 12345,
                      "name" : "Summer Special",
                      "topping" : "pineapple"
                  },
                  "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The request was successful. The response body contains the (replaced) current JSON contents of the document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                },
                "example": {
                  "id": "52046945-53be-4552-b632-d855a13e9c90",
                  "schemaNamespace": "test",
                  "schemaName": "pizza",
                  "values": {
                      "vegetarian": true,
                      "orderNumber": 12345,
                      "name" : "Summer Special",
                      "topping" : "pineapple"
                  },
                  "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          },
          "404": {
            "description": "The request failed because no document exists with this ID."
          }
        }
      },
      "patch": {
        "tags": [
          "document"
        ],
        "summary": "Update an existing document",
        "description": "Replace a subset of values in an existing document.<br><br>If the associated schema has been updated since the last time this document was written, this latest schema version will be applied.",
        "operationId": "patchDocument",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The UUID that identifies the document.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The new document values (JSON), which will replace the current values (but leave other values unchanged).<br><br>The content must adhere to the latest version of the associated schema. Any existing values no longer supported by the latest schema version will be removed.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentUpdate"
              },
                "example": {
                  "id": "52046945-53be-4552-b632-d855a13e9c90",
                  "schemaNamespace": "test",
                  "schemaName": "pizza",
                  "values": {
                      "vegetarian": false,
                      "topping" : "pepperoni"
                  },
                  "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The request was successful. The response body contains the (updated) current JSON contents of the document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                },
                "example": {
                  "id": "52046945-53be-4552-b632-d855a13e9c90",
                  "schemaNamespace": "test",
                  "schemaName": "pizza",
                  "values": {
                      "vegetarian": false,
                      "orderNumber": 12345,
                      "name" : "Summer Special",
                      "topping" : "pepperoni"
                  },
                  "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          },
          "404": {
            "description": "The request failed because no document exists with this ID."
          }
        }
      },
      "get": {
        "tags": [
          "document"
        ],
        "summary": "Get an existing document",
        "description": "Retrieve the document with the specified ID.<br><br>The values returned will adhere to the schema associated with this document the moment they were written, even if a new version of this schema has been uploaded since then.<br>Note that when this document needs to be written again, its contents must use the latest schema version.",
        "operationId": "getDocument",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The UUID that identifies the document.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The request was successful. The response body contains the current JSON contents of the document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                },
                "example": {
                  "id": "52046945-53be-4552-b632-d855a13e9c90",
                  "schemaNamespace": "test",
                  "schemaName": "pizza",
                  "values": {
                      "vegetarian": false,
                      "orderNumber": 12345,
                      "name" : "Summer Special",
                      "topping" : "pepperoni"
                  },
                  "objectId": "98fe55ec-eb9b-e911-9c52-5065f34901c9"
                }
              }
            }
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          },
          "404": {
            "description": "The request failed because no document exists with this ID."
          }
        }
      },
      "delete": {
        "tags": [
          "document"
        ],
        "summary": "Delete an existing document",
        "description": "Delete the document with the specified ID.",
        "operationId": "deleteDocument",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The UUID that identifies the document.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The request was successful."
          },
          "401": {
            "description": "The request failed because the authentication credentials were incorrect or missing."
          },
          "404": {
            "description": "The request failed because no document exists with this ID."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Collaboration": {
        "type": "object",
        "properties": {
          "collaborationId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "VersionedSchema": {
        "type": "object",
        "properties": {
          "namespace": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "fields": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Field"
            }
          },
          "schemas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Schema"
            }
          },
          "types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "publishedForRepository": {
            "type": "number"
          }
        },
        "required": [
          "namespace",
          "name",
          "fields",
          "schemas",
          "types",
          "publishedForRepository"
        ],
        "additionalProperties": false
      },
      "Field": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "schema": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "schema"
        ]
      },
      "Schema": {
        "type": "object",
        "properties": {
          "kind": {
            "enum": [
              "enum"
            ]
          },
          "name": {
            "type": "string"
          },
          "literals": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/EnumLiteral"
            }
          }
        },
        "required": [
          "name",
          "kind"
        ],
        "anyOf": [
          {
            "properties": {
              "kind": {
                "enum": [
                  "enum"
                ]
              }
            },
            "required": [
              "literals"
            ]
          }
        ]
      },
      "EnumLiteral": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        }
      },
      "DocumentCreate": {
        "type": "object",
        "properties": {
          "objectId": {
            "type": "string"
          },
          "schemaNamespace": {
            "type": "string"
          },
          "schemaName": {
            "type": "string"
          },
          "values": {
            "type": "object",
            "minProperties": 1
          }
        },
        "required": [
          "objectId",
          "schemaNamespace",
          "schemaName",
          "values"
        ],
        "additionalProperties": false
      },
      "DocumentUpdate": {
        "properties": {
          "values": {
            "type": "object",
            "minProperties": 1
          }
        },
        "required": [
          "values"
        ],
        "additionalProperties": false
        },
      "Document": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "schemaNamespace": {
            "type": "string"
          },
          "schemaName": {
            "type": "string"
          },
          "values": {
            "type": "object",
            "minProperties": 1
          }
        },
        "additionalProperties": false
      },
      "Object": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "fq_class_name": {
            "type": "string"
          },
          "name": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          }
        }
      }
     }
  },
  "security": [
    {
      "oAuth2ClientCredentials": []
    }
  ]
}

Finding type names

When using the Open API for requesting elements, their type names are needed to access the correct information. These type names can be found using the Metamodel Browser or you can use a script to generate a list of available type names in your model.

Using the Metamodel Browser

The Metamodel Browser can be accessed via the Query tool script editor. The Metamodel Browser contains the names of all elements, attributes and enumeration values of all the elements available in the metamodel of a model, including any customizations that have been made to the configuration of the metamodel.

Clicking the Metamodel button in the script editor will open the Metamodel Browser window. Type the name of the element you are looking for in the search box, and click Search. The result in Name will show the type name.


Using a script

Lists of type names can be generated using a script. The script can be executed in the script editor and needs the "Table" output type. Following scripts are available:

Code Block
// Find the type of 1 object, selected in the model browser.

output selection[1].type().name();


Code Block
// Find the type of all objects in the current open model package.

nameType = Index();
forall List("AbstractCompound", "AbstractElement") obj in modelpackage {
      nameType.add( obj.type().toString(), obj.type().name() );
}
forall name, type in nameType {
      output name, type;
}


Code Block
// Find all possible types in a metamodel (whether present in the model package or not).

metamodel = "ArchiMate";
nameType = Index();
forall c in InternalObject("configuration").context(modelpackage).metaModel(metamodel).concepts(true) {
      if ( c.derivesFrom("AbstractCompound") || c.derivesFrom("AbstractElement") ) {
           nameType.add( c.label( modelpackage.activeLanguage() ), format("%s:%s", c.metaModel().name(), c.name()) );
      }
}
forall name, type in nameType {
      output name, type;
}


Example of a list generated with a script