PyCOA - Leseapp

API documentation

API follows JSON:API conventions (see jsonapi.org)

Basically, there are only two actions: Submitting a solution to the PyCOA backend and retrieving the current level of a user.

Terms and definitions

AppUser: An end user of the VHS reading app. Identified by a sourced ID.

Sourced ID: An ID used by the source system to store and retrieve user data. Sourced IDs are unique, i.e. same sourced ID refers to same user, different sourced ID refers to different user. Usually, this is a crypotgraphically hashed ID.

Practice: An attempt of a lesson which can be correct or not and may have more data attached (e.g. from the speech recognition component)

Authorization

There are two authorization methods implemented as of now:

1. HTTP Basic Auth

Authenticate via standard HTTP Basic Auth with username and password.

2. Token Authorization

For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:

Authorization: Token 44556677889900aabbccddee

Submitting a solution

POST https://pycoa.de/api/practices/
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "Practice",
        "id": null,
        "attributes": {
            "user_id": @USER_ID@,
            "lesson": @LESSON_ID@,
            "lesson_alpha_level": @LESSON_ALPHA_LEVEL@,
            "lesson_sub_level": @LESSON_ALPHA_SUB_LEVEL@,
            "correct": @PRACTICE_CORRECTNESS@,
            "data": @PRACTICE_DATA@
        }
    }
}

The variables indicated by @...@ have to filled as follows:

Variable	Type	Value
LESSON_ID	String	Unique ID of the lesson
LESSON_ALPHA_LEVEL	Integer	1-4 (Alpha level the lesson is designed for
LESSON_SUB_LEVEL	String	"a" or "b" (Sublevel the lesson is designed for
PRACTICE_CORRECTNESS	Boolean	Was the solution correct?
PRACTICE_DATA	JSON	More info on solution (TO BE DEFINED)

Note: Alpha Level one does not have sublevels, LESSON_SUB_LEVEL is left out then.

Getting a user's current level

Information about a user can be obtained from a GET request including to user's sourced id.

GET https://pycoa.de/api/users/@USER_ID@

Response:

HTTP/1.1 200 OK
Date: Wed, 10 Aug 2022 13:46:01 GMT
Content-Type: application/vnd.api+json

{"data":
  {"type":"AppUser",
   "id":"u123456",
   "attributes": 
     {"user_id":"u123456",
      "alpha_level":1,
      "sub_level":"a"}
    }
}                                                                                                  (

CURL examples

POST a new practice result

curl -u user:password -d '{ "data": { "type": "Practice", "id": null, "attributes": {"user_id":"u123456", "lesson":"lesson123-1", "lesson_alpha_level":2, "lesson_sub_level":"a", "correct":false, "data":{"velo":23}}}}' -H "Content-Type: application/vnd.api+json" -X POST http://127.0.0.1:8000/api/practices/

GET current user level

curl -u user:password -X GET http://127.0.0.1:8000/api/users/u123456/

Contact

Tobias Thelen: tt@tobiasthelen.de, +49 1522 / 874 86 80

Change API token

``` python manage.py shell from rest_framework.authtoken.models import Token

token = Token.objects.get(user=...) print(token.key) `