WOCAT Website API¶

Old version: https://redmine.cde.unibe.ch/projects/wocat-cms/wiki/WebServicesAuthentificationAddress

Requirements:¶

- All requests over encrypted connection (SSL)
- All responses as JSON
- Authentication for service is needed (eg. token authentication http://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication)
- Documentation is available (eg. http://django-rest-swagger.readthedocs.io/en/latest/)

End points:¶

- Authentication

/[v1]/authentication
    Method: POST
    Data:
      - username
      - password
    Response:
      - JSON user object if login successful
      - Response with HTTP status code 401 if login not successful

- List of users (with search)

/[v1]/users
    Method: GET
    Query parameters:
      - name (username or first/lastname)
    Response:
      - List of JSON user objects
      {
          "users": [
            // List of JSON user objects
          ],
          "count": 2  // the total count (without limit)
        }

- Details of user

/[v1]/users/[id]
    Method: GET
    URL parameter:
      - id
    Response:
      - JSON user object if found
      - Response with HTTP status code 404 if not found

- List of institutions

/[v1]/institutions
    Method: GET
    Response:
      - List of JSON institution objects
      {
          "users": [
            // List of JSON institution objects
          ],
          "count": 2  // the total count (without limit)
        }

- List of projects

/[v1]/projects
    Method: GET
    Response:
      - List of JSON project objects
      {
          "users": [
            // List of JSON project objects
          ],
          "count": 2  // the total count (without limit)
        }

Response formats¶

Format of JSON user object:

{
    "uid": 1055,
    "username": "kurt.gerber@cde.unibe.ch",
    "first_name": "Kurt",
    "last_name": "Gerber",
    "usergroup": [
    {
        "name": "UNCCD Focal Point",
        "unccd_country": "CHE" 
      }
    ],
    "address": "Hallerstrasse 10",
    "zip": "3012",
    "city": "Bern",
    "country": "Switzerland",
    "institution": {
      "name": "CDE",
      "id": 1
    }
  }

Format of JSON institution object:

{
    "name": "CDE",
    "id": 1
  }

Format of JSON project object:

{
    "name": "DRR project",
    "id": 1
  }

Open questions:¶

- Can users have more than 1 institution?
- SSO with cookie?
- Authentication token periodically changing?