WOCAT » QCAT

h1. WOCAT Website API

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

h2. Requirements:

- Website with [[wocat_web_users_def|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/)

h2. End points:

h3. Authentication

* URL: @/[v1]/authentication@

* Method: POST

* Data:

> * username

> * password

* Response:

> * *JSON user object* if login successful

> * Response with HTTP status code 401 if login not successful

h3. List of users (with search)

* URL: @/[v1]/users@

* Method: GET

* Query parameters:

> * name (partial email or first/lastname )

* Response:

> * *List of JSON user objects*

> <pre>

{

  "users": [

    // List of JSON user objects

  ],

  "count": 2  // the total count (without limit)

}

</pre>

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

h3. List of institutions

* URL: @/[v1]/institutions@

* Method: GET

* Response:

> * *List of JSON institution objects*

> <pre>

{

  "institutions": [

    // List of JSON institution objects

  ],

  "count": 2  // the total count (without limit)

}

</pre>

h3. List of projects

* URL: /[v1]/projects

* Method: GET

* Response:

> * *List of JSON project objects*

> <pre>

{

  "projects": [

    // List of JSON project objects

  ],

  "count": 2  // the total count (without limit)

}

</pre>

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",

    "country": "CHE",

    "id": 1

  }

*Format of JSON project object:*

  {

    "name": "DRR project",

    "id": 1

  }

h2. Open questions:

- Can users have more than 1 institution?

> No, users have only one insitution

- SSO with cookie?

> Would be great.

- Authentication token periodically changing?