Wiki Markup |
---|
Syncope's REST API has changed from version *<<placeholder>>* to *<<placeholder>>*. |
...
This page shall give you an overview of old and new REST API. These changes will only affect REST URLs, content models have not been changed. |
...
Main focus on redesign REST interface was: |
...
# applying [RESTful Best |
...
Practices|http://www.slideshare.net/calamitas/restful-best-practices] #* use HTTP operations instead of URL encoded operation names #* GET does not modify any object (read-only safety operation) |
...
#* PUT and DELETE are idempotent operations |
...
# use URL parameters for search and filter restrictions |
...
In the near feature I would also like to replace the current search NodeCond with [FIQL searchqueries |
...
Role Interface
CRUD operations:
Old URL | New URL | Comment |
---|---|---|
POST /role/create | POST /roles/ | Creates a new role. Returns URL to new role definition |
GET /role/list | GET /roles | Returns a list of all known roles |
GET /role/read/{roleId} | GET /roles/{roleId} | Returns a single role definition matching the provided roleID |
GET /role/selfRead/{roleId} | GET /roles/{roleId} | Authorization mechanisms will be independent of URL |
GET /role/parent/{roleId} | GET /roles/{roleId}/parent | Returns a single parent role definition (if available) |
GET /role/children/{roleId} | GET /roles/{roleId}/children | Returns a list of children role definitions |
POST /role/update | POST /roles/{roleId} | Updates role. (POST is used here instead of PUT, because RoleMod only contains changes for a role and not a complete representation thereof.) |
GET /role/delete/{roleId} | DELETE /roles/{roleId} | Deletes role. |
User Interface
CRUD operations:
Old URL | New URL | Comment |
---|---|---|
POST /user/create | POST /user/ | Creates a new user. (Returns URL to new user definition?) |
GET /user/list | GET /user | Returns a list of all known users |
GET /user/list/{page}/{size} | GET /user?page={page}&size={size} | Returns a list of known users matching page/size conditions |
GET /user/read/{userId} | GET /user/{userId} | Returns a single user matching the provided userId |
GET /user/readByUsername/{username} | GET /user;uname={username} | Returns a single user matching the provided username |
POST /user/search | GET /user?{search} | Returns a list of user matching the provided search conditions. |
POST /user/search/{page}/{size} | POST /user?{search}&page={page}&size={size} | Returns a list of user matching the provided page/size and search conditions. |
GET /user/count | GET /user/count | Returns a number of existing users. |
POST /user/search/count | POST /user/count?{search} | Returns a number of user matching the provided search conditions. |
GET /user/verifyPassword/{username}?password={password} | GET /user;uname={username};pwd={password} | Returns user if username and password match with an existing account. |
POST /user/update | POST /user/{userId} | Updates user. (POST is used here instead of PUT, because UserMod only contains changes for a user and not a complete representation thereof.) |
GET /user/delete/{userId} | DELETE /user/{userId} | Deletes user. |
GET /deleteByUsername/{username} | <<removed>> | Please use 'GET /user?uname={username}' to discover userId and then use 'DELETE /user/{userId}' to delete user. |
Account status:
Old URL | New URL | Comment |
---|---|---|
GET /user/activate/{userId} | PUT /user/{userId}/status/active | Enables a user account. |
GET /user/activateByUsername/{username} | <<removed>> | Please use 'GET /user?uname={username}' to discover userId and then use 'PUT /user/{userId}/status/active' to enable user account. |
GET /user/reactivate/{userId} | PUT /user/{userId}/status/active | Reactivates a user account. |
GET /user/reactivateByUsername/{username} | <<removed>> | Please use 'GET /user?uname={username}' to discover userId and then use 'PUT /user/{userId}/status/active' to reactivate user account. |
GET /user/suspend/{userId} | DELETE /user/{userId}/status/active | Disables a user account. |
<<none>> | GET /user/{userId}/status/active | Returns HTTP-Status-Code 204 (200?) if user is enabled. Returns HTTP-Status-Code 404 if user is disabled. |
GET /user/suspendByUsername/{username} | <<removed>> | Please use 'GET /user?uname={username}' to discover userId and then use 'DELETE /user/{userId}/status/active' to disable user account. |
Workflow actions: TODO: Is this a good design decision? Should these activities be moved to WorkflowController?
...
Old URL
...
New URL
...
Comment
...
GET /user/workflow/form/list
...
GET /user/workflow/form
...
Returns a list of user workflow forms.
...
GET /user/workflow/form/{userId}
...
GET /user/{userId}/workflow/form
...
Returns a (single) workflow form assigned to user.
...
POST /user/workflow/form/submit
...
POST /user/workflow/form
...
Submittes a form to a user workflow.
...
POST /user/execute/workflow/{taskId}
...
POST /user/workflow/task/{taskId}/execute
...
Executes workflow task on user.
...
GET /workflow/form/claim/{taskId}
...
POST /user/workflow/task/{taskId}/claim
...
|http://cxf.apache.org/docs/jax-rs-advanced-features.html#JAX-RSAdvancedFeatures-FIQLsearchqueries].
h2. Role Interface
CRUD operations:
|| Old URL || New URL || Comment ||
| POST /role/create | POST /roles/ | Creates a new role. Returns URL to new role definition |
| GET /role/list | GET /roles | Returns a list of all known roles |
| GET /role/read/\{roleId\} | GET /roles/\{roleId\} | Returns a single role definition matching the provided roleID |
| GET /role/selfRead/\{roleId\} | GET /roles/\{roleId\} | Authorization mechanisms will be independent of URL |
| GET /role/parent/\{roleId\} | GET /roles/\{roleId\}/parent | Returns a single parent role definition (if available) |
| GET /role/children/\{roleId\} | GET /roles/\{roleId\}/children | Returns a list of children role definitions |
| POST /role/update | POST /roles/\{roleId\} | Updates role. (POST is used here instead of PUT, because RoleMod only contains changes for a role and not a complete representation thereof.) |
| GET /role/delete/\{roleId\} | DELETE /roles/\{roleId\} | Deletes role. |
h2. User Interface
CRUD operations:
|| Old URL || New URL || Comment ||
| POST /user/create | POST /user/ | Creates a new user. _(Returns URL to new user definition)_ |
| GET /user/list | GET /user | Returns a list of all known users |
| GET /user/list/\{page\}/\{size\} | GET /user?page=\{page\}&size=\{size\} | Returns a list of known users matching page/size conditions |
| GET /user/read/\{userId\} | GET /user/\{userId\} | Returns a single user matching the provided userId |
| GET /user/readByUsername/\{username\} | GET /user;uname=\{username\} | Returns a single user matching the provided username |
| POST /user/search | POST /user/search | Returns a list of user matching the provided search conditions. |
| POST /user/search/\{page\}/\{size\} | POST /user/search?page=\{page\}&size=\{size\} | Returns a list of user matching the provided page/size and search conditions. |
| GET /user/count | GET /user/count | Returns a number of existing users. |
| POST /user/search/count | POST /user/count | Returns a number of user matching the provided search conditions. |
| GET /user/verifyPassword/\{username\}?password=\{password\} | GET /user;uname=\{username\};pwd=\{password\} | Returns user if username and password match with an existing account. |
| POST /user/update | POST /user/\{userId\} | Updates user. (POST is used here instead of PUT, because UserMod only contains changes for a user and not a complete representation thereof.) |
| GET /user/delete/\{userId\} | DELETE /user/\{userId\} | Deletes user. |
| GET /deleteByUsername/\{username\} | <<removed>> | Please use 'GET /user;uname=\{username\}' to discover userId and then use 'DELETE /user/\{userId\}' to delete user. |
Account status:
|| Old URL || New URL || Comment ||
| GET /user/activate/\{userId\} | POST /user/{userId}/status | Post a new StatusMod element with status ACTIVATE. |
| GET /user/activateByUsername/\{username\} | <<removed>> | Please use 'GET /user;uname=\{username\}' to discover userId and then use 'POST /user/{userId}/status' to enable user account. |
| GET /user/reactivate/\{userId\} | POST /user/{userId}/status | Post a new StatusMod element with status REACTIVATE. |
| GET /user/reactivateByUsername/\{username\} | <<removed>> | Please use 'GET /user;uname=\{username\}' to discover userId and then use 'POST /user/{userId}/status' to reactivate user account. |
| GET /user/suspend/\{userId\} | POST /user/{userId}/status | Post a new StatusMod element with status SUSPEND. |
| GET /user/suspendByUsername/\{username\} | <<removed>> | Please use 'GET /user;uname=\{username\}' to discover userId and then use 'POST /user/{userId}/status' to suspend user account. |
Workflow actions: {color:red}{_}TODO: Is this a good design decision? Should these activities be moved to WorkflowController?_{color}
|| Old URL || New URL || Comment ||
| GET /user/workflow/form/list | GET /user/workflow/form | Returns a list of user workflow forms. |
| GET /user/workflow/form/\{userId\} | GET /user/\{userId\}/workflow/form | Returns a (single) workflow form assigned to user. |
| POST /user/workflow/form/submit | POST /user/workflow/form | Submittes a form to a user workflow. |
| POST /user/execute/workflow/\{taskId\} | POST /user/workflow/task/\{taskId\}/execute | Executes workflow task on user. |
| GET /workflow/form/claim/\{taskId\} | POST /user/workflow/task/\{taskId\}/claim | Claims workflow task for authenticated (session) user. | |