Migrate from v1 to v2

Added

We introduced a feature that allows switching between API versions. See Using the API page.

Removed

To make JSON serialization easier, we removed the links section. As a result, all endpoints that return a list of items had to be restructured.

  1. API v1.

{
  "_links": {
	"next": "/projects?size=5&page=2",
	"self": "/projects?size=5",
	"last": "/projects?size=5&page=4",
	"first": "/projects?size=5&page=1"
  },
  "projects": [
	{
	  "id": 14,
	  ...
	}
  ]
}

Becomes

API v2.
[
  {
	"id": 14,
	...
  }
]
Table 1. Updated endpoints.

Type

Tag

Endpoint

GET

Project

/api/projects

GET

Project

/api/projects/{project-id}

GET

Project

/api/projects/{project-id}/versions

GET

Project

/api/projects/{project-id}/artefacts

GET

Artefact

/api/artefacts/{artefact-id}/logs

GET

Artefact

/api/artefacts/{artefact-id}/findings

GET

Artefact

/api/artefacts/{artefact-id}/actionItems

GET

Artefact

/api/artefacts/{artefact-id}/children

GET

Artefact

/api/artefacts/{artefact-id}/links

GET

Artefact

/api/artefacts/{artefact-id}/highlightDefinitions

GET

Artefact

/api/artefacts/{artefact-id}/measures

GET

Artefact

/api/artefacts/{artefact-id}/indicators

GET

Artefact

/api/artefacts/{artefact-id}/reportDefinitions

GET

Artefact

/api/artefacts/{artefact-id}/chartDefinitions

GET

Artefact

/api/artefacts/{artefact-id}/tableDefinitions

GET

Artefact

/api/artefacts/{artefact-id}/exportDefinitions

GET

Artefact

/api/artefacts/{artefact-id}/forms

GET

Model

/api/models/{model-id}/exportDefinitions

GET

Model

/api/models/{model-id}/wizardDefinitions

GET

Model

/api/models/{model-id}/exportDefinitions

GET

Model

/api/models/{model-id}/highlightDefinitions

GET

Model

/api/models/{model-id}/projects

GET

Model

/api/models

GET

Branch

/api/branches/{branch-id}/versions

GET

Branch

/api/branches/{branch-id}/artefacts

GET

Version

/api/versions/{version-id}/artefacts

GET

Tool

/api/tools

GET

Group

/api/groups/{group-id}/members

GET

Group

/api/groups/{group-id}/roles

GET

Permission

/api/permissions

GET

Role

/api/roles

GET

Role

/api/roles/{role-id}/permissions

GET

User

/api/users

GET

User

/api/users/{user-id}/groups

GET

User

/api/users/{user-id}/roles

Updated

Simplified API path

We removed some path parameters and moved those values into query parameters.

In the example below, the versionId was previously passed as a path parameter (left side), but it is now included as a query parameter.

/versions/{version-id}/artefacts/{artefact-id}

Becomes

/artefacts/{artefact-id}?versionId={versionId}

Table 2. Updated endpoint.

v1

V2

/versions/{version-id}/artefacts/{artefact-id}

/artefacts/{artefact-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/exportDefinitions

/artefacts/{artefact-id}/exportDefinitions?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/exportDefinitions/{export-id}

/artefacts/{artefact-id}/exportDefinitions/{export-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/exports/{export-id}

/artefacts/{artefact-id}/exports/{export-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/forms

/artefacts/{artefact-id}/forms?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/tableDefinitions

/artefacts/{artefact-id}/tableDefinitions/{table-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/tableDefinitions/{table-id}

/artefacts/{artefact-id}/tableDefinitions?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/chartDefinitions

/artefacts/{artefact-id}/chartDefinitions?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/chartDefinitions/{chart-id}

/artefacts/{artefact-id}/chartDefinitions/{chart-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/charts/{chart-id}

/artefacts/{artefact-id}/charts/{chart-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/reportDefinitions

/artefacts/{artefact-id}/reportDefinitions?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/reportDefinitions/{report-id}

/artefacts/{artefact-id}/reportDefinitions/{report-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/reports/{report-id}

/artefacts/{artefact-id}/charts/{report-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/context

/artefacts/{artefact-id}/context?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/logs

/artefacts/{artefact-id}/logs?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/parent

/artefacts/{artefact-id}/parent?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/children

/artefacts/{artefact-id}/children?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/links

/artefacts/{artefact-id}/links?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/actionItems

/artefacts/{artefact-id}/actionItems?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/indicators

/artefacts/{artefact-id}/indicators?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/measures/{measure-id}

/artefacts/{artefact-id}/measures/{measure-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/measures

/artefacts/{artefact-id}/measures?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/highlightDefinitions

/artefacts/{artefact-id}/highlightDefinitions?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/highlightDefinitions/{highlight-id}

/artefacts/{artefact-id}/highlightDefinitions/{highlight-id}?versionId={versionId}

/versions/{version-id}/artefacts/{artefact-id}/highlights/{highlight-id}

/artefacts/{artefact-id}/highlights/{highlight-id}?versionId={versionId}

/versions/{version-id}/tools

/tools?versionId={versionId}

/versions/{version-id}/tools/{tool-id}

/tools/{tool-id}?versionId={versionId}

/projects/{project-id}/tools

/tools?project={projectIdOrName}

/projects/{project-id}/tools/{tool-id}

/tools/{tool-id}?project={projectIdOrName}

Change the date format

In API v1 the date format is a complex timestamp. API v2 changed it with a human-readable string formatted date.

"analysisTime": 1655331650466

Becomes

"analysisTime": "2022-06-02T15:04:39.572+0000"

Table 3. Updated endpoints

Type

Tag

Endpoint

GET

Project

/api/projects

GET

Project

/api/projects/{project-id}

GET

Project

/api/projects/{project-id}/versions

GET

Project

/api/projects/{project-id}/artefacts

GET

Server

/api/about

GET

Artefact

/api/artefacts/{artefact-id}/logs

GET

Artefact

/api/artefacts/{artefact-id}/findings

GET

Artefact

/api/artefacts/{artefact-id}/actionItems

GET

Artefact

/api/artefacts/{artefact-id}

GET

Artefact

/api/artefacts/{artefact-id}/children

GET

Finding

/api/findings/{finding-id}

GET

Action item

/api/actionitems/{actionItems-id}

GET

Task

/api/tasks/{task-id}

GET

Branch

/api/branches/{branch-id}/versions

GET

Branch

/api/branches/{branch-id}

GET

Version

/api/versions/{version-id}

GET

Version

/api/versions/{version-id}/artefacts

GET

Model

/api/models/{model-id}/projects

Update the project field name branchId to mainId

To use more precise terminology, we now refer to the branchId as mainId to clearly indicate that it represents the main branch.

DtoProject.branchId

Becomes

DtoProject2.mainId

Update 200 status to 201 after creation

All POST endpoints that create data are affected by this change. To improve compliance with REST standards, they now return a 201 Created status instead of 200 OK.

Table 4. Updated endpoints.

Type

Endpoint

POST

/api/projects

POST

/api/artefacts/id/comments

POST

/api/artefacts/id/charts/id/comments

POST

/api/branches/id

POST

/api/versions/id/branches/name

POST

/api/groups

POST

/api/roles

POST

/api/users