API endpoints

CodeMapper endpoints

We assume the following base URL for CodeMapper (it will change once the new version will be published):

BASE_URL=https://app.vac4eu.org/codemapper-testing

Note that the endpoints for mappings (get info, revision, CSV export) work only on mappings that were saved in the new version of CodeMapper, otherwise the endpoint returns an error. (The app manages the fallback to recover from old versions.)

The documentation of the HTTP endpoints uses the following format:

> METHOD URL
> REQUEST_HEADERS
REQUEST_BODY

< RESPONSE_HEADERS
RESPONSE_BODY

When endpoints respond with JSON data, the shape of the data is described using the pattern <JSON: Type> and a TypeScript definition of that type.

1. Login

Authentication of the protected endpoints is done using a cookie. The cookie is provided in the response header of the login-endpoint and must be send in the header of all requests to protected endpoints. (There is an issue to improve on that.)

> POST <BASE_URL>/rest/authentification/login
> Content-Type: application/x-www-form-urlencoded
username<USERNAME>&password=<PASSWORD>

< Set-Cookie: <COOKIE>
< Content-Type: application/json
<JSON: LoginResult>

type LoginResult = {success: true, user: any} | {success: false, error: string}

2. Get your projects

Get the list of all projects that you can access, and your role. You can export the mappings as CSV of all projects where your role is "Editor" or "Owner"

> GET <BASE_URL>/rest/persistency/user/project-permissions
> Cookie: <COOKIE>

< Content-Type: application/json
<JSON: ProjectsRoles>

type ProjectsRoles = { [key : string] : ProjectRole }
enum ProjectRole {
  Owner = "Owner",
  Editor = "Editor",
  Commentator = "Commentator"
}

3. Get infos about mappings in a project

Get information about all mappings in a project. The mapping shortkeys are used to identify mappings in other endpoints.

> GET <BASE_URL>/rest/persistency/projects/<PROJECT_NAME>/mappings
> Cookie: <COOKIE>

< Content-Type: application/json
<JSON: MappingInfo[]>

interface MappingInfo {
  projectName : string;
  mappingName : string;
  mappingShortkey : string;
}

4. Get revision infos of a mapping

Get information about all revisions of a mapping, to find the latest one.

> GET <BASE_URL>/rest/persistency/mapping/<MAPPING_SHORTKEY>/revisions
> Cookie: <COOKIE>

< Content-Type: application/json
<JSON: Revision[]>

interface Revision {
  version : number;
  author : string;
  timestamp : string;
  summary : string;
}

5. Export mapping as CSV

> GET <BASE_URL>/rest/rest/code-mapper/code-lists-csv?project=<PROJECT_NAME>&includeDescendants=true&compatibilityFormat=true&mappings=<MAPPING>&...
> Cookie: <COOKIE>

< Content-Type: text/csv
event_definition,coding_system,code,code_name,concept,concept_name,tags,origin,system,event_abbreviation,type
...

The query parameter mappings can be added several times to include the code lists of several mappings in the CSV. Each <MAPPING> is either a mapping shortkey (e.g. abcdfg), or a mapping short key and the version separated by @ (e.g. abcdfg@3). If the version is not specified it defaults to the latest version.