API version 2

[timobrembeck]

Motivation

Implement a second improved version of the API

Proposed Solution

Terminology

The app uses the same data model for groups, disciplines and training sets. Thus, we should adapt the CMS models as well and reflect this structure in the API.

• groups are now root disciplines with an apiKey
• training sets are leaf disciplines
• documents are words.

Endpoints

Disciplines

Endpoint	Result
/api/v2/disciplines/	All global disciplines
/api/v2/disciplines/?level=0	All global root disciplines
/api/v2/disciplines/?keys[]=key1&keys[]=key2	All global and private disciplines with the given keys
/api/v2/disciplines/?level=0&keys[]=key1&keys[]=key2	All global and private root disciplines with the given keys
/api/v2/disciplines/?parent_id=1	The children of the global discipline with the given id
/api/v2/disciplines/?parent_id=1&keys[]=key1	The children of the private discipline with the given id and key
/api/v2/disciplines/:disciplineId/	The global discipline with the given id
/api/v2/disciplines/:disciplineId/?keys[]=key1	The private discipline with the given id and key

Words

Endpoint	Result
/api/v2/words/	All global vocabulary words
/api/v2/words/?keys[]=key1&keys[]=key2	All global and private vocabulary words with the given keys
/api/v2/words/?ids[]=1&ids[]=2	All global vocabulary words with the given ids
/api/v2/words/?ids[]=1&ids[]=2&keys[]=key1&keys[]=key2	All global and private vocabulary words with the given ids and keys
/api/v2/words/?discipline_id=1	The vocabulary words of the global discipline with the given id (only works if the discipline is a leaf)
/api/v2/words/?discipline_id=1&keys[]=key1	The vocabulary words of the private discipline with the given id and key (only works if the discipline is a leaf)
/api/v2/words/:wordId/	The global vocabulary word with the given id
/api/v2/words/:wordId/?keys[]=key1	The private vocabulary word with the given id and key

Return format

Disciplines

id: number
title: string
description: string
icon: string
numberOfChildren: number
isLeaf: boolean
parentTitle: string | null // if null then it is the root discipline
apiKey?: string
leafDisciplines?: number[]
"tree": [
  {
    "id": 1,
    "name": "level-1a",
    "tree": [
      {
        "id": 5,
        "name": "level2-a",
        "tree": []
      },
      {
        "id": 4,
        "name": "level2-b",
        "tree": []
      },
    ],
  },
  {
    "id": 3,
    "name": "level-1b",
    "tree": [],
  },
  {
    "id": 2,
    "name": "level-1c",
    "tree": [],
  },
], // nested list of descendants

Words

Identical to API v1

Return codes

• 404: "The key is valid, but there are no disciplines with this key"
• 403: "The key is invalid"

[ztefanie]

We should think about using graphQL for the api.