API Versioning: Platform Upgrades

How to handle versions

There are two approaches to API access. The difference between the approaches how the connected system will behave across Platform releases - when there is a new API version.

1. "Unversioned" API, i.e. teneo-studio/rest/auth/ will always access the current version of the API
   • Before platform upgrade, this targets the pre-upgrade API version - after platform upgrade, this targets the latest post-upgrade API
   • This approach only requires maintenance effort in the connecting system if there are breaking changes in the new API version in the endpoints used by the system
   • This approach however means if there are breaking changes in the endpoints in use, then the system will not properly connect until it is updated
2. Explicit API version, e.g. teneo-studio/rest/vX/auth/ to access a specified version (where vX is the version number)
   • Allows the connecting system to continue working across upgrade, supported a scheduled migration, after the platform upgrade
     • Before and after platform upgrade, the system explicitly targets the pre-upgrade API version vX so will continue functioning
     • After upgrade schedule a migration of the connecting code to target post-upgrade API version vY
   • Guarantees seamless support across platform versions
     • NOTE the migration must be carried out before the next platform upgrade as the old (vX) version is only available for 1 platform release
   • This approach however requires upgrade effort for every new API version, even if there are no breaking changes in the in use endpoints

These versioning approaches are completely interoperable:

• Some systems can use the unversioned API whilst some use the explicit version API
• Multiple Systems using the explicit API version approach can be migrated 1 by 1 over time

Platform Upgrades

In preparation for a Platform upgrade, review the release notes which include specific changes made between versions - then follow the guidelines below based on the type of API usage application.

Details for Teneo 8.0 Upgrade: Teneo 8.0 - API Changes

For non critical applications

1. Use the generic endpoints (/(component)/rest/(endpoint))
2. Check the release notes for breaking changes affecting in use endpoints
3. After Platform Upgrade, update and test the connected system before running it for a new version

For business critical applications

These are application where the processing is automated and must seamlessly work without changes across upgrades

1. Before upgrade: ensure all endpoints explicitly specify the correct version for the current release
2. Check the release notes for breaking changes affecting in use endpoints
3. After upgrade: test and rollout code which explicitly specifies the correct version for the new release

What is not included in API versioning

Batch requests are not included in the previous version of the API and will return a 404 not found error. The batch request endpoint will only work on the current version. This is because if you had the ability to call the previous version and current version endpoints in a mix using batch requests, it could cause unpredictable side effects and data corruption.

Enums are not versionable and therefore usage of them must be flexible. Users of the API must be ready for unknown values as old values may be removed and new values added.

How to handle tasks: Information on managing asynchronous processes

Studio

Starting a task

To start a task, there is an associated begin endpoint.

Here is an example calling the begin endpoint associated with batch restoring from the recycle bin in JavaScript:

fetch(`${server}/teneo-studio/rest/recycle-bin/batch-restore/begin/${solutionId}`, {
    method: 'post',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
    body: JSON.stringify(documentIds),
})

Task begin endpoints return a UUID corresponding to that task's identifier.

Checking a task's status

To check a task's status, there is an endpoint to retrieve tasks using a tasks identifier: teneo-studio/rest/tasks/{taskId}

This will return a model with a status that indicates if the task has finished successfully. Here is an example of that model:

{
  "errorCode": "IMPORT_EXCEPTION",
  "errorMessage": "Invalid solution file",
  "id": "b3c0c1df-ed64-4a7b-99ee-c10b3e065dcb",
  "priority": "HIGH",
  "status": "FAILED",
  "userId": "a0045227-0a5b-4ef5-9cf9-557954a9af2d"
}

The web socket API can also be used for this by receiving task events.

Obtaining a task result

Tasks also have an endpoint to get the task's result. This is obtainable using the task's identifier.

Here is an example retrieving the task result for a batch operation restore from recycle bin task in JavaScript:

fetch(`${server}/teneo-studio/rest/recycle-bin/batch-restore/result/${taskId}`, {
    method: 'get',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
})

In the event of a success, the document identifier and path of the document associated with the task is returned in a SuccessReport to allow for further usage, e.g. a newly created solution.

Here is an example of that model:

  {
    "documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "jobId": "7cc336fd-2817-44e9-8f7f-79cb5a6deaa7",
    "name": "documentName",
    "path": "/318e16f7-0248-4fd3-b988-3c4c0ebbfa5a/28991677-c01a-4f15-a91a-3a85767f755b/5c4cfdb6-4034-46ff-bcff-85f29211f977/9bb631e1-57b3-4f4f-9714-f98880fd69ba",
    "success": true
  }

In the event of an error, an error code and description of the error is also provided in an ErrorReport. Here is an example of that model:

{
  "errorCode": "TASK_EXCEPTION",
  "details": "Task failed"
}

If you try to obtain a task's result before the task has finished or if the task is cancelled you will also get the above model with the details stating that the task has not finished or has been cancelled.

Cancelling a task

Task endpoints have a single endpoint used to cancel a task: teneo-studio/rest/tasks/cancel/{taskId}

Here is an example of using the cancel endpoint in JavaScript:

fetch(`${server}/teneo-studio/rest/tasks/cancel/${taskId}`, {
    method: 'post',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
})

Inquire

Starting a query

The only tasks that exist in Inquire are TQL queries. There are multiple query endpoints. Query endpoints return a StartExecutionMessage. This model has an id that can then be used to poll for results.

Here is an example showing how to execute a shared TQL query in JavaScript:

fetch(`${server}/teneo-inquire/rest/tql/shared-queries/submit/${ldsName}?identifier=${identifier}&timeout=${timeout}&validateQuery=${bool}`{
    method: 'post',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
})

Here is an example of a StartExecutionMessage:

{
  "error": false,
  "executionConfiguration": {
    "commandExecutionOnly": true,
    "executeCommandIteratively": true,
    "limitDuringExecution": true,
    "timeEstimate": "fast"
  },
  "id": "11699639-9f3c-445e-9b7f-539069da0149",
  "lds": "ldsName",
  "mainCommand": "cu",
  "phases": "bind com.artisol.teneo.inquire.tql.processor.planner.datasource.InEsDatasource@281ebd8a",
  "query": "cu s.id",
  "result": {},
  "time": 0
}

Polling for query results

The endpoint teneo-inquire/rest/tql/poll is used to retrieve the status of a query using its identifier. Queries can take a while to complete. However, they can return partial results, i.e. the results for the query that have been discovered prior to completion of the query. When completed, they return a FinalResultMessage.

Here is an example polling for a result using an identifier in JavaScript:

fetch(`${server}/teneo-inquire/rest/tql/poll?id=${queryId}&timeout=${timeout}`{
    method: 'get',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
})

Here is an example of a FinalResultMessage:

{
  "id": "37f94b65c5a246faa72e3df8da31a966",
  "lds": "ldsName",
  "query": "cu s.id",
  "error": false,
  "time": 511,
  "result": [
    {
      "s.id": 3528
    }
  ]
}

Cancelling a query

A query can be cancelled using the endpoint teneo-inquire/rest/tql/cancel?id=${id}.

Here is an example of cancelling a query using an identifier in JavaScript:

fetch(`${server}/teneo-inquire/rest/tql/cancel?id=${queryId}`{
    method: 'get',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
})

Error Handling

If the user is unauthenticated, the server returns a 401 unauthorized error.

In case of internal server errors, a 500 error is returned.

In case of bad requests, a 400 error is returned.

Inquire's error model contains a message that provides details on the error, a code corresponding to the HTTP status code, and a type describing the type of error. Here is an example:

{
  "message": "Unauthorized login attempt",
  "code": 401,
  "type": "AUTHENTICATION"
}

Studios error model always contains an ErrorCode and details on the error. Here is an example:

{
  "ErrorCode": "USER_NOT_LOGGED_IN",
  "details": "Unauthorized login attempt"
}

The model may also contain extra fields in the event of certain errors that have more useful information for a user.

Locks: Details on locking documents

Studio POST and PUT endpoints that create or modify documents can also have an optional LockToken header. The LockToken is used to prove you are the owner of a lock on a locked document to prevent modification by another user at the same time.

To obtain a lock token for a document the locks/{solutionId}/{documentId} POST endpoint should be used. Here is an example of that in JavaScript:

fetch(`${server}/teneo-studio/rest/locks/${solutionId}/${documentId}` {
    method: 'post',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
})

When you are finished with a document you must unlock it, otherwise the document will unlock when your session expires. This can cause multiple issues in multi-user scenarios.

To unlock a document use the locks/{lockToken} DELETE endpoint. Here is an example of that in JavaScript:

fetch(`${server}/teneo-studio/rest/locks/${lockToken}` {
    method: 'delete',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json"
    },
})

Comments: Details on handling Solution Log Comments

Studio POST and PUT endpoints that create or modify documents can also have an optional comment header.

The comment header is used to set a comment for the solution log entry associated with an action that creates said entry.

Here’s an example of adding a comment to a batch restore from the recycle bin in JavaScript:

fetch(`${server}/teneo-studio/rest/recycle-bin/batch-restore/begin/${solutionId}`, {
    method: 'post',
    headers: {
        "Authorization": `Bearer ${authentication}`,
        "Content-type": "application/json",
        "Comment": "${comment}"
    },
    body: JSON.stringify(documentIds),
})