Skip to content

Latest commit

 

History

History
136 lines (102 loc) · 4.28 KB

Rest-user.md

File metadata and controls

136 lines (102 loc) · 4.28 KB

User

< Rest API documentation

The user resources is used to make the binding between the annotations tool context (i.e. ilias or sakai) and the annotation tools itself for the users management.

Base URI

http://api.annotationstool.com/v1/users

Attributes

Name Type Description Default
id* Long The user id for the annotation tool. Generated at creation
user_extid* String The user id for the used video portal/system (i.e. Opencast Matterhorn). This id will be used by the annotations tool to make the binding with the user from the current context. EMPTY
nickname* String The user nickname. EMPTY
email String User email address. NULL
+ logging attributes

* = required

Operations

Update or create a user

Update the user with the given user_extid or create a new one with this user_extid.

Method Path Parameters HTTP Response
PUT /users/ user_extid, email, nickname 200 Ok: Resource modified, 201 created: Resource created.

Example Request

Url

PUT http://api.annotationstool.com/v1/users/

Content

user_extid=R2D2&nickname=RobotsKing&email=[email protected]

Response Content

{
 id: 1,
 user_extid: 'R2D2', 
 nickname: 'RobotsKing',
 email: '[email protected]'
}

Response Header

X-ANNOTATIONS-USER-AUTH-TOKEN X-ANNOTATIONS-USER-USER-ID LOCATION (url to the created / updated resource) Required for creation AND update!!!

Create a new user

Create a user. Email, Nickname are not enforced unique.

Method Path Parameters HTTP Response
POST /users NONE 201 Created: Resource created, 400 Bad request: Request not valid, 401 Unauthorized: Operation not authorized for the user, 409 conflict: Resource already exist, 500 Internal server error: Error happened on the server side.

Example request

Url

POST http://api.annotationstool.com/v1/users

Content

id=1&user_extid=R2D2&nickname=RobotsKing&[email protected]

Response content

Location parameter in header give the URI from the new resource.

{
 id: 1,
 user_extid: 'R2D2', 
 nickname: 'RobotsKing',
 email: '[email protected]'
}

Get a user

NO MORE USED

staubesv, 09-18-2012:

  • The request GET /users/:id is only allowed if it is sent by the (logged-in) user :id. This restriction makes it impossible to enumerate all other users from the database and gain access to their private data (e.g. e-mail address)
  • It is not yet clear whether we need this request at all (the logged-in user always executes a update_or_create_user request and therefore is aware of its own data)

Get a user

Method Path Parameters HTTP Response
GET /users/:id NONE 200 Ok: Resource returned, 401 Unauthorized: Operation not authorized for the user, 404 Not found: Resource not found, 500 Internal server error: Error happened on the server side.

Example request

Url

GET http://api.annotationstool.com/v1/users/1

Content

NO CONTENT

Response content

{
 id: 1,
 user_extid: 'R2D2', 
 nickname: 'RobotsKing',
 email: '[email protected]'
}

Delete a user

Delete the user with the given id. Only the logged-in user :id can execute DELETE /users/:id.

staubesv, 09-18-2012:

  • Semantic of deletion to be defined
Method Path Parameters HTTP Response
DELETE /users/:id NONE 204 No content: Resource deleted, 401 Unauthorized: Operation not authorized for the user, 404 Not found: Resource not found.

Example request

Url

DELETE http://api.annotationstool.com/v1/users/1

Content

NO CONTENT

Response content

NO CONTENT

< Rest API documentation [1]: rest-get-parameters