REST API upgrade

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

There are some also suggestions regarding remote exceptions propagation

Role Service

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 Service

CRUD operations:

Old URL	New URL	Comment
POST /user/create	POST /users	Creates a new user. (Returns URL to new user definition)
GET /user/list	GET /users	Returns a list of all known users
GET /user/list/{page}/{size}	GET /users?page={page}&size={size}	Returns a list of known users matching page/size conditions
GET /user/read/{userId}	GET /users/{userId}	Returns a single user matching the provided userId
GET /user/readByUsername/{username}	GET /users;uname={username}	Returns a single user matching the provided username
POST /user/search	POST /users/search	Returns a list of user matching the provided search conditions.
POST /user/search/{page}/{size}	POST /users/search?page={page}&size={size}	Returns a list of user matching the provided page/size and search conditions.
GET /user/count	GET /users/count	Returns a number of existing users.
POST /user/search/count	POST /users/search/count	Returns a number of user matching the provided search conditions.
GET /user/verifyPassword/{username}?password={password}	GET /users;uname={username};pwd={password}	Returns user if username and password match with an existing account.
POST /user/update	POST /users/{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 /users/{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 /users/{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 /users/{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 /users/{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: 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 /users/workflow/form	Returns a list of user workflow forms.
GET /user/workflow/form/{userId}	GET /users/{userId}/workflow/form	Returns a (single) workflow form assigned to user.
POST /user/workflow/form/submit	POST /users/workflow/form	Submittes a form to a user workflow.
POST /user/execute/workflow/{taskId}	POST /users/workflow/task/{taskId}/execute	Executes workflow task on user.
GET /workflow/form/claim/{taskId}	POST /users/workflow/task/{taskId}/claim	Claims workflow task for authenticated (session) user.

Entitlement Service

Old URL	New URL	Comment
GET /auth/allentitlements	GET /entitlements	Returns a list of all known entitlements.
GET /auth/entitlements	GET /entitlements/own	Returns a list of entitlements assigned to the authenticated user.

Configuration Service

Old URL	New URL	Comment
POST /configuration/create	POST /configurations	Creates a new Configuration.
GET /configuration/delete/{key}	DELETE /configurations/{key}	Deletes configuration with matching key.
GET /configuration/list	GET /configurations	Returns a list of all configuration elements.
GET /configuration/read/{key}	GET /configurations/{key}	Returns configuration element with matching key.
POST /configuration/update	PUT /configurations/{key}	Overwrites configuration element with matching key.
GET /configuration/validators	GET /configurations/validators	Returns a list of known validators.
GET /configuration/mailTemplates	GET /configurations/mailTemplates	Returns a list of known mail-templates.
GET /configuration/dbexport	GET /configurations (Accept: application/octet-stream)	Returns configuration as an downloadable content.xml database export file.

Connector Service

Old URL	New URL	Comment
POST /connectors/create	POST /connectors/	Creates a new connector instance.
GET /connectors/delete/{connectorId}	DELETE /connectors/{connectorId}	Deletes connector with matching id.
GET /connectors/list	GET /connectors	Returns a list of all connectors.
GET /connectors/read/{connectorId}	GET /connectors/{connectorId}	Returns connector with matching id.
POST /connectors/update	PUT /connectors/{connectorId}	Overwrites connector with matching key.
GET /connectors/bundle/list?lang={lang}	GET /connectors/bundles?lang={lang}	Returns known bundles. Default language is English.
POST /connectors/schema/list?showall={showall}	GET /connectors/{connectorId}/schemas?showall={showall} POST /connectors/{connectorId}/schemas?showall={showall}	Returns schema names for connector. Default is showAll=false.
GET /connectors/{connectorId}/configurationProperty/list	GET /connectors/{connectorId}/configuration	Returns configuration for selected connector.
POST /connectors/check	POST /connectors/validate	Validates connection.
GET /connectors/{resourceName}/connectorBean	GET /connectors;resourceName={connectorId}	Returns connection for resourceName.

Logger Service

Old URL	New URL	Comment
GET /logger/log/list	GET /logger	Returns a list of all (normal) logger.
GET /logger/audit/list	GET /logger/audit	Returns a list of all audit logger.
POST /logger/log/{name}/{level}	PUT /logger/{name}/level	Creates or updates a logger with given name and sets logging level. Level will be now be part of payload instead of URL parameter.
GET /logger/delete/{name}	DELETE /logger/{name}	Deletes logger with matching name.
PUT /logger/audit/enable	<<removed>>	Use "PUT /logger/{name}/level" to enables audit logger.
PUT /logger/audit/disable	<<removed>>	Use "DELETE /logger/{name}" to disable audit logger.

Report Service

Old URL	New URL	Comment
POST /report/create	POST /reports	Creates a new report.
POST /report/update	PUT /reports/{reportId}	Updates report with matching reportId.
POST /report/count	POST /reports/count	Returns number of existing reports.
GET /report/list	GET /reports	Returns a list of all reports.
GET /report/list/{page}/{size}	GET /reports?page={page}&size={size}	Returns a list of reports according to pagination.
GET /report/execution/list	GET /reports/executions	Returns a list of all execution reports.
GET /report/reportletConfClasses	GET /reports/reportletConfClasses	Returns a list of all reportletConfClasses.
GET /report/read/{reportId}	GET /reports/{reportId}	Returns report with matching reportId.
GET /report/execution/read/{executionId}	GET /reports/executions/{executionId}	Returns execution report.
GET /report/execution/export/{executionId}?fmt={format}	GET /reports/executions/{executionId}?format={format} (Accept: application/octet-stream)	Returns execution report as an downloadable file. Format is optional.
POST /report/execute/{reportId}	POST /reports/{reportId}/execute	Executes report.
GET /report/delete/{reportId}	DELETE /reports/{reportId}	Deletes report with matching id.
GET /report/execution/delete/{executionId}	DELETE /reports/executions/{executionId}	Deletes execution report with matching id.

Resource Service

Old URL	New URL	Comment
POST /resource/create	POST /resources	Creates a new resource.
POST /resource/update	PUT /resources/{resourceName}	Updates resource with matching resourceName. HTTP operation is changed to PUT, because method is idempotent.
GET /resource/delete/{resourceName}	DELETE /resources/{resourceName}	Deletes resource with specified resourceName. HTTP operation is changed to DELETE, because GET operation must be safe.
GET /resource/read/{resourceName}	GET /resources/{resourceName}	Returns a resource with specified name.
GET /resource/propagationActionsClasses	GET /resources/propagationActionsClasses	Returns a list of classes with name PROPAGATION_ACTIONS. Actually method is used only in context of resources, therefore it is grouped to resources.
GET /resource/list	GET /resources	Returns a list of all resources. There is optional matrix parameter: connInstanceId.
GET /resource/{resourceName}/read/{type}/{objectId}	GET /resources/{resourceName}/{type}/{objectId}	Returns specified connector object for resource.
POST /resource/check	POST /resources/validate	Verifies connection using resource connector parameters. HTTP operation can be changed to GET if resource is always created previously.

Page tree