WOCAT » QCAT

h1. WOCAT Website API

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

h2. 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/)

h2. 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)

        }

h2. 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

  }

h2. Open questions:

- Can users have more than 1 institution?

- SSO with cookie?

- Authentication token periodically changing?