Advanced Identity Cloud REST
Advanced Identity Cloud REST is a REST API framework defining common APIs to access web resources and collections of resources.
Resources
Endpoints generally return JSON-format resources, though resource formats can depend on the implementation.
Resources in collections can be found by their unique identifiers (IDs).
IDs are exposed in the resource URIs.
For example, if a service has a user collection under /users, you can access a user at /users/user-id.
The ID is also the value of the _id field of the resource.
Resources are versioned using revision numbers.
A revision is specified in the resource’s _rev field.
Revisions make it possible to figure out whether to apply changes
without resource locking and without distributed transactions.
Verbs
The Advanced Identity Cloud REST APIs use the following verbs, sometimes referred to collectively as CRUDPAQ. For details and HTTP-based examples of each, follow the links to the sections for each verb.
| Verb | Description |
|---|---|
Add a new resource with HTTP PUT or HTTP POST. |
|
Retrieve a single resource with HTTP GET. |
|
Replace an existing resource with HTTP PUT. |
|
Remove an existing resource with HTTP DELETE. |
|
Modify part of an existing resource with HTTP PATCH. |
|
Perform a predefined action with HTTP POST. |
|
Search a collection of resources with HTTP GET. |
Query parameters
Advanced Identity Cloud REST reserved query string parameter names start with an underscore (_).
Reserved query string parameters include, but are not limited to, the following names:
_action
_api
_countOnly
_crestapi
_fields
_mimeType
_pageSize
_pagedResultsCookie
_pagedResultsOffset
_prettyPrint
_queryExpression
_queryFilter
_queryId
_sortKeys
_totalPagedResultsPolicy
| Some parameter values are not safe for URLs; URL-encode parameter values as necessary. |
Extension points
The action verb is the main vehicle for extensions.
For example, to create a new user with HTTP POST rather than HTTP PUT, you might use /users?_action=create.
An endpoint can define additional actions.
For example, /tasks/1?_action=cancel.
A service can define stored queries to call by ID.
For example, /groups?_queryId=hasDeletedMembers.
Stored queries can call for additional parameters.
The parameters are also passed in the query string.
Which parameters are valid depends on the stored query.