WOCAT Website API¶

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

Requirements:¶

- Website with Users/Groups/Institutions and Adresses in place
- 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¶

• URL: /[v1]/authentication
• Method: POST
• Data:

• username
• password

• Response:

• JSON user object if logi> successful
• Response with HTTP status code 401 if login not successful

List of users (with search)¶

• URL: /[v1]/users
• Method: GET
• Query parameters:

• name (partial email 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¶

• URL: /[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¶

• URL: /[v1]/institutions
• Method: GET
• Response:

• List of JSON institution objects
  

  {
    "institutions": [
      // List of JSON institution objects
    ],
    "count": 2  // the total count (without limit)
  }
  

List of projects¶

• URL: /[v1]/projects
• Method: GET
• Response:

• List of JSON project objects
  

  {
    "projects": [
      // 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",
    "country": "CHE",
    "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?