WOCAT » QCAT

Wiki »

WOCAT Website API » History » Revision 8

Revision 7 (Kurt Gerber, 16 Jun 2016 15:18) → Revision 8/9 (Kurt Gerber, 20 Jun 2016 10:36)

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 JSON user object* object if login logi> 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?