--- title: Common REST description: Common REST is a common REST API framework. It works across the Ping Identity platform to provide common ways to access web resources and collections of resources. Adapt the examples in this section to your resources and deployment. component: pingidm version: 8.1 page_id: pingidm::crest/about-crest canonical_url: https://docs.pingidentity.com/pingidm/8.1/crest/about-crest.html keywords: ["Rest", "REST API"] section_ids: about-crest-resources: Common REST Resources about-crest-verbs: Common REST Verbs about-crest-parameters: Common REST Parameters about-crest-extensions: Common REST Extension Points about-crest-api-descriptors: Common REST API Documentation use-openapi-descriptors: Publish OpenAPI Documentation --- # Common REST Common REST is a common REST API framework. It works across the Ping Identity platform to provide common ways to access web resources and collections of resources. Adapt the examples in this section to your resources and deployment. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This section describes the full Common REST framework. Some platform component products do not implement all Common REST behaviors exactly as described in this section. For details, refer to the product-specific examples and reference information in other sections of this documentation set. | ## Common REST Resources Servers 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 server has a user collection under `/users`, then 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. ## Common REST Verbs The Common 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. * Create Add a new resource. This verb maps to HTTP PUT or HTTP POST. For details, refer to [Create](crest-create.html). * Read Retrieve a single resource. This verb maps to HTTP GET. For details, refer to [Read](crest-read.html). * Update Replace an existing resource. This verb maps to HTTP PUT. For details, refer to [Update](crest-update.html). * Delete Remove an existing resource. This verb maps to HTTP DELETE. For details, refer to [Delete](crest-delete.html). * Patch Modify part of an existing resource. This verb maps to HTTP PATCH. For details, refer to [Patch](crest-patch.html). * Action Perform a predefined action. This verb maps to HTTP POST. For details, refer to [Action](crest-action.html). * Query Search a collection of resources. This verb maps to HTTP GET. For details, refer to [Query](crest-query.html). ## Common REST Parameters Common 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`\ `_crestapi`\ `_fields`\ `_mimeType`\ `_pageSize`\ `_pagedResultsCookie`\ `_pagedResultsOffset`\ `_prettyPrint`\ `_queryExpression`\ `_queryFilter`\ `_queryId`\ `_sortKeys`\ `_totalPagedResultsPolicy` | | | | - | ----------------------------------------------------------------------------------------- | | | Some parameter values are not safe for URLs, so URL-encode parameter values as necessary. | Continue reading for details about how to use each parameter. ## Common REST 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`. A server can define additional actions. For example, `/tasks/1?_action=cancel`. A server 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. ## Common REST API Documentation Common REST APIs often depend at least in part on runtime configuration. Many Common REST endpoints therefore serve *API descriptors* at runtime. An API descriptor documents the actual API as it's configured. Use the following query string parameters to retrieve API descriptors: * `_api` Serves an API descriptor that complies with the [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification). This API descriptor represents the API accessible over HTTP. It's suitable for use with popular tools, such as [Swagger UI](https://swagger.io/tools/swagger-ui/). | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Requests made with the `_api` query string parameter require authorization. Grant access by creating a custom rule in `access.json`. The following example authorizes users with the `openidm-authorized` role:```json { "pattern" : "managed/user", "roles" : "internal/role/openidm-authorized", "methods" : "read", "customAuthz" : "checkIfApiRequest()" } ``` | * `_crestapi` Serves a native Common REST API descriptor. This API descriptor provides a compact representation that is not dependent on the transport protocol. It requires a client that understands Common REST because it omits many Common REST defaults. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Consider limiting access to API descriptors in production environments to avoid unnecessary traffic.To provide documentation in production environments, refer to [Publish OpenAPI Documentation](#use-openapi-descriptors) instead. | ### Publish OpenAPI Documentation In production systems, developers expect stable, well-documented APIs. Rather than retrieving API descriptors at runtime through Common REST, prepare final versions, and publish them alongside the software in production. Use the OpenAPI-compliant descriptors to provide API reference documentation for your developers as described in the following steps: 1. Configure the software to produce production-ready APIs. In other words, the software should be configured as in production so that the APIs are identical to what developers refer to in production. 2. Retrieve the OpenAPI-compliant descriptor. The following command saves the descriptor to a file, `myapi.json`: ``` curl -o myapi.json endpoint?_api ``` 3. If necessary, edit the descriptor. For example, you might want to add security definitions to describe how the API is protected. If you make any changes, then also consider using a source control system to manage your versions of the API descriptor. 4. Publish the descriptor using a tool, such as [Swagger UI](https://github.com/swagger-api/swagger-ui). You can customize Swagger UI for your organization as described in the documentation for the tool.