You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 43 Next »

Version warning

In Syncope 1.1.0 a new REST interface was introduced (referred as new in the following).

The REST interface available in 1.0.X (referred as old in the following) is still present but will be removed from releases >= 1.2.0.

This page shall give you an overview of old and new REST API.

Main focus on redesign REST interface was to apply 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
    • PUT and DELETE do not return (old) object any longer, except for Roles and Users, since they contain propagation status information
  • CREATE operations return location URL in header for newly created object
    • In addition to that unique identifier of resource is also send in response header (org.apache.syncope.resource.id)

While redesigning interface, we also made changes to exception handling.

Configuration Service

Old URL

New URL

Comment

POST /configuration/create

POST /configurations

Creates a new Configuration.

GET /configuration/read/{key}

GET /configurations/{key}

Returns configuration element with matching key.

GET /configuration/list

GET /configurations

Returns a list of all configuration elements.

POST /configuration/update

PUT /configurations/{key}

Overwrites configuration element with matching key.

GET /configuration/delete/{key}

DELETE /configurations/{key}

Deletes configuration with matching key.

Old URL

New URL

Comment

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/dbDump

Returns configuration as an downloadable content.xml database export file.

Connector Service

Old URL

New URL

Comment

POST /connector/create

POST /connectors

Creates a new connector instance.

GET /connector/read/{connectorId}

GET /connectors/{connectorId}

Returns connector with matching id.

GET /connector/list?lang={lang}

GET /connectors?lang={lang}

Returns a list of all connectors. Default language is English.

POST /connector/update

PUT /connectors/{connectorId}

Overwrites connector with matching key.

GET /connector/delete/{connectorId}

DELETE /connectors/{connectorId}

Deletes connector with matching id.

Old URL

New URL

Comment

GET /connector/bundle/list?lang={lang}

GET /connectors/bundles?lang={lang}

Returns known bundles. Default language is English.

POST /connector/schema/list?showall={showall}

POST /connectors/{connectorId}/schemas?showAll={showall}

Returns schema names for connector. Default is showAll=false.

GET /connector/{connectorId}/configurationProperty/list

GET /connectors/{connectorId}/configuration

Returns configuration for selected connector.

POST /connector/check

POST /connectors/check

Checks if a connection can be established.

GET /connector/{resourceName}/connectorBean

GET /connectors;resourceName={connectorId}

Returns connector for resourceName.

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.

Logger Service

Old URL

New URL

Comment

POST /logger/log/{name}/{level}

PUT /logger/normal/{name}

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/log/list

GET /logger/normal

Returns a list of all normal logger.

GET /logger/delete/{name}

DELETE /logger/normal/{name}

Deletes normal logger with matching name.

Old URL

New URL

Comment

PUT /logger/audit/enable

PUT /logger/audit/{name}

Creates or updates audit logger with matching name.

GET /logger/audit/list

GET /logger/audit

Returns a list of all audit logger.

PUT /logger/audit/disable

DELETE /logger/audit/{name}

Deletes audit logger with matching name.

Notification Service

Old URL

New URL

Comment

GET /notification/list

GET /notifications/

Returns a list of all notifications.

GET /notification/read/{notificationId}

GET /notifications/{notificationId}

Returns a notification with matching id.

POST /notification/create

POST /notifications

Creates a new notification.

POST /notification/update

PUT /notifications/{notificationId}

Updates notification with matching id.

GET /notification/delete/{notificationId}

DELETE /notifications/{notificationId}

Deletes notification with matching id.

Policy Service

Old URL

New URL

Comment

GET /policy/{kind}/list

GET /policies/{kind}

Returns a list of policies with matching kind.

GET /policy/read/{id}

GET /policies/{id}

Returns a policy with matching id.

POST /policy/account/create

POST /policies

Creates a new account policy.

POST /policy/sync/create

POST /policies

Creates a new sync policy.

POST /policy/password/create

POST /policies

Creates a new password policy.

POST /policy/account/update

PUT /policies/{id}

Updates policy with matching id.

POST /policy/sync/update

PUT /policies/{id}

Updates policy with matching id.

POST /policy/password/update

PUT /policies/{id}

Updates policy with matching id.

GET /policy/delete/{id}

DELETE /policies/{id}

Deletes policy with matching id.

GET /policy/account/global/read

DELETE /policies/global/{kind}

Returns global policy for matching kind.

GET /policy/sync/global/read

DELETE /policies/global/{kind}

Returns global policy for matching kind.

GET /policy/password/global/read

DELETE /policies/global/{kind}

Returns global policy for matching kind.

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.

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.

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.

Schema Service

Old URL

New URL

Comment

GET /schema/{kind}/list

GET /schemas/{kind}/{type}

Returns a list of all "normal" schema definitions of matching kind.

GET /virtualSchema/{kind}/list

GET /schemas/{kind}/{type}

Returns a list of all "virtual" schema definitions of matching kind.

GET /derivedSchema/{kind}/list

GET /schemas/{kind}/{type}

Returns a list of all "derived" schema definitions of matching kind.

POST /schema/{kind}/create

POST /schemas/{kind}/{type}

Creates a new "normal" schema for matching kind.

POST /virtualSchema/{kind}/create

POST /schemas/{kind}/{type}

Creates a new "virtual" schema for matching kind.

POST /derivedSchema/{kind}/create

POST /schemas/{kind}/{type}

Creates a new "derived" schema for matching kind.

GET /schema/{kind}/delete/{name}

DELETE /schemas/{kind}/{type}/{name}

Deletes matching schema.

GET /virtualSchema/{kind}/delete/{name}

DELETE /schemas/{kind}/{type}/{name}

Deletes matching schema.

GET /derivedSchema/{kind}/delete/{name}

DELETE /schemas/{kind}/{type}/{name}

Deletes matching schema.

GET /schema/{kind}/read/{name}

GET /schemas/{kind}/{type}/{name}

Returns matching schema.

GET /virtualSchema/{kind}/read/{name}

GET /schemas/{kind}/{type}/{name}

Returns matching schema.

GET /derivedSchema/{kind}/read/{name}

GET /schemas/{kind}/{type}/{name}

Returns matching schema.

POST /schema/{kind}/update

PUT /schemas/{kind}/{type}/{name}

Updates matching schema.

POST /virtualSchema/{kind}/update

PUT /schemas/{kind}/{type}/{name}

Updates matching schema.

POST /derivedSchema/{kind}/update

PUT /schemas/{kind}/{type}/{name}

Updates matching schema.

Task Service

Old URL

New URL

Comment

POST /task/create/sync

POST /tasks

Creates a new (sync) task.

POST /task/create/sched

POST /tasks

Creates a new (sched) task.

GET /task/{kind}/count

GET /tasks/{kind}/count

Returns number of tasks for matching kind.

GET /task/delete/{taskId}

DELETE /tasks/{taskId}

Deletes task with matching id.

GET /task/execution/delete/{executionId}

DELETE /tasks/executions/{executionId}

Deletes execution of task with matching id.

POST /task/execute/{taskId}?dryRun={dryRun}

POST /tasks/{taskId}/execute?dryRun={dryRun}

Executes task with matching id.

GET /task/jobClasses

GET /tasks/jobClasses

Returns a list of available jobClasses.

GET /task/syncActionsClasses

GET /tasks/syncActionsClasses

Returns a list of available syncActionsClasses.

GET /task/{kind}/list

GET /tasks/{kind}

Returns a list of task of matching kind.

GET /task/{kind}/list/{page}/{size}

GET /tasks/{kind}?page={page}&size={size}

Returns a list of task of matching kind with page contrains.

GET /task/{kind}/execution/list

GET /tasks/{kind}/executions

Returns list of executions with matching kind.

GET /task/read/{taskId}

GET /tasks/{taskId}

Returns task with matching id.

GET /task/execution/read/{executionId}

GET /tasks/executions/{executionId}

Returns execution of task with matching id.

POST /task/update/sync

PUT /tasks/{taskId}

Updates (sync) task with matching id.

POST /task/update/sched

PUT /tasks/{taskId}

Updates (sched) task with matching id.

GET /task/execution/report/{executionId}
?executionStatus={executionStatus}&message={message}

POST /tasks/executions/{executionId}/report

Creates a report for matching execution id.

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.

UserRequest Service

Old URL

New URL

Comment

GET /user/request/create/allowed

GET /requests/user/create/allowed

Returns true/false whether user is allowed to create a new user.

POST /user/request/create

POST /requests/user/create

Creates a new user creation request.

POST /user/request/update

POST /requests/user/update

Creates a new user update request.

GET /user/request/delete/{userId}

POST /requests/user/delete

Creates a new user delete request. (Id will now be part of HTTP body)

GET /user/request/list

GET /requests/user

Returns a list of all user requests.

GET /user/request/read/{requestId}

GET /requests/user/{requestId}

Returns a user request with matching id.

GET /user/request/deleteRequest/{requestId}

DELETE /requests/user/{requestId}

Deletes request with matching id.

Workflow Service

Old URL

New URL

Comment

GET /workflow/definition/user

GET /workflows/{kind}

Returns a workflow definition of matching kind.

GET /workflow/definition/role

GET /workflows/{kind}

Returns a workflow definition of matching kind.

PUT /workflow/definition/user

PUT /workflows/{kind}

Creates or updates workflow definition of matching kind.

PUT /workflow/definition/role

PUT /workflows/{kind}

Creates or updates workflow definition of matching kind.

GET /workflow/tasks/user

GET /workflows/{kind}/tasks

Returns workflow tasks with matching kind.

  • No labels