Make your first API requests

Find a repository, list its models, and recognize a model by name. This walkthrough only reads data. You can use your server's Swagger in a browser or the Bash commands alongside each step.

Prepare your connection#

Get your server address, an API key, and a repository/model name to look for. Ask your administrator for access if you do not have them yet. The examples use a fictional Process library containing Handle an order; your names and identifiers will differ.

Use Swagger on your server#

1. Open https://your-server.example/mt-backend/swagger/, replacing the example host with your server's address. You need network access to that server, which may require your organization's VPN.
2. Choose Authorize, paste the application API key into the x-api-key security entry, choose Authorize, then Close. Paste only the key, without Bearer or quotes.
3. Follow the GET operations below. Expand an operation, choose Try it out, enter its parameters, and choose Execute. Look under Server response for the actual response code and body. The Example Value is illustrative documentation, not a request result.

The public reference at developer.2c8.com cannot execute requests. Use Swagger on your own server for these steps. Keep the key out of URLs, support messages and screenshots. Your application key may also permit writes; use only the operations in this tutorial.

export API_BASE_URL='https://your-server.example/mt-backend/api/v1'
read -r -s -p 'API key: ' API_KEY
printf '\n'
export API_KEY

List repositories#

In Swagger, open Repositories → GET /api/v1/repositories and choose Try it out:

Leave other parameters at their defaults, then choose Execute.

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $API_KEY" \
  "$API_BASE_URL/repositories?projection=SIMPLE&startAt=0&maxResults=10"

Expect HTTP 200, meaning the request succeeded. Example response:

{
  "startAt": 0,
  "maxResults": 10,
  "total": 1,
  "data": [
    {
      "uuid": "603055e8-4734-461e-bf42-d4456afe7bb7",
      "name": "Process library"
    }
  ]
}

data contains the repositories returned on this page; total counts all matching repositories. Find a name you recognize and copy its uuid from your response, not this example. This value is the next request's repositoryId.

If total is greater than the number of returned entries, read the next page. If the list is empty, check the repository data. If you receive HTML or a login page, check the address.

Reference: List repositories.

List models in a repository#

In Swagger, open Models → GET /api/v1/repositories/{repositoryId}/models and choose Try it out:

Leave other parameters at their defaults, then choose Execute.

export REPOSITORY_ID='REPLACE_WITH_REPOSITORY_UUID'

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $API_KEY" \
  "$API_BASE_URL/repositories/$REPOSITORY_ID/models?projection=SIMPLE&fields=titles&startAt=0&maxResults=10"

Example HTTP 200 response:

{
  "startAt": 0,
  "maxResults": 10,
  "total": 2,
  "data": [
    {
      "uuid": "c022603a-4d79-4b5e-a82e-ce1f2916b2c0",
      "modelType": "GENERAL_MODEL",
      "titles": {
        "b030a9f8-a89c-41c4-a972-0da5763c4d95": {
          "title": "Handle an order"
        }
      }
    },
    {
      "uuid": "a41979d0-f088-44e5-828c-bd12ce9e0196",
      "modelType": "GENERAL_MODEL",
      "titles": {
        "b030a9f8-a89c-41c4-a972-0da5763c4d95": {
          "title": "Dispatch an order"
        }
      }
    }
  ]
}

Find a model name inside titles. In this example it is Handle an order. The long key inside titles identifies the language; it is not the model's ID. The model's own uuid is next to modelType. Keep it together with the repository UUID for later requests.

You have now found a named model through the API. The catalogue walkthrough explains how to match title languages and build a readable list. If names are missing, see There are no model names.

Reference: List models.

Continue building#

• Understand models, symbols, vertices, and edges.
• Read the model's canvas, descriptions and documents.
• Handle pagination and select fields.
• Resolve a 401, 403, or other error.

When finished in Swagger, choose Authorize → Logout for the API key. When finished in Bash, clear the variable:

unset API_KEY