Skip to content

API endpoints

Jump to bottom
Benedikt Becker edited this page Oct 9, 2024 · 5 revisions

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 TypeScript types.

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>

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>
< <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>
< <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>
< <JSON: Revision[]>

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

5. Export mapping as CSV

GET <BASE_URL>/rest/code-mapper/export-mapping-csv?mapping=<MAPPING_SHORTKEY>&version=<REVISION_VERSION>&includeDescendants=<bool>
Cookie: <COOKIE>
< # Mapping: <NAME>, version: <VERSION>, project: <PROJECT>, created with CodeMapper
< Coding system,Code,Code name,Concept,Concept name,Tags,Origin
< ...

The version is optional. It can be the version number of a revision, and defaults to the version of the latest revision.

Clone this wiki locally