--- title: API responses description: The PingOne API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body. component: pingone-api page_id: pingone-api:foundations:conventions/pingone-api-responses canonical_url: https://developer.pingidentity.com/pingone-api/foundations/conventions/pingone-api-responses.html section_ids: http-response-headers: HTTP response headers http-response-codes: HTTP response codes synchronous-responses: Synchronous responses asynchronous-responses: Asynchronous responses response-data-structure: Response data structure relationships-links-and-references: Relationships, links, and references caching: Caching --- # API responses ## HTTP response headers The PingOne API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body. The following HTTP Headers are returned by every operation: * `Access-Control-Allow-Headers` Used in response to a cross-origin resource sharing (CORS) preflight request to indicate the HTTP headers that can be used when making a request. * `Access-Control-Allow-Max-Age` Specifies how long the results of a CORS preflight request can be cached. * `Access-Control-Allow-Methods` Specifies the method or methods allowed when accessing the resource in response to a CORS preflight request. * `Cache-Control` Specifies directives for caching mechanisms in both requests and responses. * `Content-Type` Specifies the data exchange format for the response data. * `Correlation-Id` A custom header. * `Date` Shows the date the response was sent. * `Expires` Shows the date and time when the response expires. * `Pragma` Used for backwards compatibility with HTTP/1.0 caches in which the Cache-Control HTTP/1.1 header is not yet present. * `Strict-Transport-Security` Allows a web site to tell browsers that the site should only be accessed using HTTPS, instead of HTTP. * `Transfer-Encoding` Specifies the form of encoding used to safely transfer the entity to the user. * `Vary` Determines how to match future request headers to decide whether a cached response can be used rather than requesting a fresh one from the origin server. It is used by the server to indicate which headers it used when selecting a representation of a resource in a content negotiation algorithm. * `Via` Used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of senders along the request/response chain. * `X-Content-Type-Options` A marker used by the server to indicate that the MIME types advertised in the Content-Type headers should not be changed and be followed. * `X-Frame-Options` This denies rendering in a frame where there is a frame mismatch. * `X-XSS-Protection` A feature of Internet Explorer, Chrome, and Safari that stops pages from loading when the browsers detect reflected cross-site scripting (XSS) attacks. ## HTTP response codes The PingOne API returns the status of an operation as a registered HTTP response code. The HTTP response codes can be summarized as: * `200-299` Confirms a successful call. * `300-399` Indicates that the call or subsequent calls should be made to another resource. * `400-499` Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters. * `500-599` Shows that an error occurred, generally due to an issue with the service (for example, a service outage). Operations can also return additional information about a failed operation in the HTTP response body. ### Synchronous responses Responses for synchronous operations have the following behavior: * `GET` operations A request that returns a body also returns the code `200 OK` with the resource in the body of the response. * `POST` operations A request that creates a new resource returns `201 CREATED` with a `Location` header containing the location of the created resource. * `PUT` or `PATCH` operations A request that updates a resource returns `200 OK` and the full resource in the body. * `DELETE` operations A request that deletes a resource returns `204 NO CONTENT`. ### Asynchronous responses The PingOne API can create a long-running or asynchronous operation that can be monitored by a client. An asynchronous operation will have the following behavior: * `POST` operations Responses include `202 ACCEPTED` with a `Location` header containing the location of the newly created operation. The client can poll the provided location to check the status of the operation. The operation may also return a suggested number of seconds for the client to recheck the status using the `Retry-After` HTTP header. * Canceling long-running operations Some resources may allow the client to cancel an operation by performing a `DELETE` request on the created resource. * Clean up The PingOne API will clean up operation history according to the application requirements (such as, keep the last `n` results, or purge results after the client has verified its success). ## Response data structure HAL (Hypertext Application Language) is a formatting convention that provides hyperlinks to related resources returned by an API request. For example, a `GET /environments/{{envID}}/users/{{userID}}` request returns data for a specific user resource. The `_links` object in the JSON response data shows the hyperlinks to related resources associated with this user. You can use the `roleAssignments` link to get role assignments associated with this user, or the `password.reset` link to perform password management actions on this user resource. ```json { "_links": { "self": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab" }, "environment": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c" }, "population": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/populations/60971d3b-cc5a-4601-9c44-2be541f91bf1" }, "devices": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/devices" }, "roleAssignments": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/roleAssignments" }, "password": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.reset": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.set": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.check": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.recover": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "linkedAccounts": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/linkedAccounts" }, "account.sendVerificationCode": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users/8376797d-641c-4e7b-8bc1-2fdf71916cab" } }, "_embedded": { "password": { "status": "PASSWORD_EXPIRED" }, "population": { "_links": { "self": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/populations/60971d3b-cc5a-4601-9c44-2be541f91bf1" }, "environment": { "href": "https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c" } }, "id": "60971d3b-cc5a-4601-9c44-2be541f91bf1" } }, "id": "8376797d-641c-4e7b-8bc1-2fdf71916cab", "environment": { "id": "5caa81af-ec05-41ff-a709-c7378007a99c" }, "createdAt": "2020-02-18T20:50:14.092Z", "email": "tomjones@example.com", "enabled": true, "lifecycle": { "status": "ACCOUNT_OK" }, "mfaEnabled": false, "name": { "given": "Tom", "family": "Jones" }, "population": { "id": "60971d3b-cc5a-4601-9c44-2be541f91bf1" }, "updatedAt": "2020-02-18T20:50:14.092Z", "username": "tomjones" } ``` In addition, the `_embedded` resources returned by the request can be used as a navigation option to explore related resources. For example, `population` is returned as an `_embedded` resource in the response, and you can use the embedded resource's `self` link to initiate a `GET /environments/{{envID}}/populations/{{popID}}` request to return data about the population associated with this user. ## Relationships, links, and references Relationships between resources or operations can be described as follows: * Relationships (one-to-one) Where a resource is directly related to another resource (such as employee to manager, user to population, logo to brand), the relationship is generally represented by an attribute as a first-class citizen of the resource. For example: * `_links` object : Contains an href to the actual resource. * Payload : Contains the reference as an attribute with the ID. The name of the `_links` attribute and the attribute in the payload must be the same). * Expandable : Yes. * Relationships (one-to-many or many-to-one) Where a resource or resources may be related to a collection or to many resources. For example, a user to group membership: * `_links` object : Contains an href to the actual resource or collection. * Payload : May contain the reference as an attribute with the ID. The name of the `_links` attribute and the attribute in the payload must be the same). * Expandable : No. * Informal relationships and links Provides navigation and self-discovery of the API and its related resources (such as next page of search results, next authentication service to invoke, or with which environment the resource is associated). For example: * `_links` object : Contains an href to the actual resource, collection, or URL. * Payload : Cannot contain the reference as an attribute. * Expandable : No. These relationships and references are represented as follows: * Links are represented using JSON HAL conventions (such as in a `_links` object). * Links are represented as absolute URLs. * Links can be expanded using the `expand` parameter. The links can also be referenced using the "property-as-resource" pattern. * References as attributes have an `id` value and can also have additional attributes (such as `displayName`). | | | | - | --------------------------------------------------------------------------------------------------------------------------------------- | | | For information about error messages, refer to [Error codes](../../platform/reference.html#error-codes) in the *PingOne Platform APIs*. | ## Caching The PingOne API generally implements HTTP caching of operation responses. When HTTP caching is implemented, the following HTTP response headers are included: * `ETag` An arbitrary string for the version of a representation. This includes the media type in the hash value. For example: `ETag`: `"686897696a7c876b7e"`. * `Date` The date and time the response was returned. For example: `Date`: `Sun, 06 Nov 1994 08:49:37 GMT`. * `Cache-Control` The maximum number of seconds a response can be cached. If caching is not supported for the response, the value is `no-cache`. For example: `Cache-Control`: `360` or `Cache-Control`: `no-cache`. * `Expires` If `Cache-Control` is supplied, this header contains the timestamp for when the response expires. If caching is not supported for the response, this header is not present. For example: `Expires`: `Sun, 06 Nov 1994 08:49:37 GMT`. * `Pragma` When the `Cache-Control` value is `no-cache`, this header is also set to `no-cache`. If caching is not supported for the response, this header is not present. For example: `Pragma`: `no-cache`. * `Last-Modified` The timestamp for when the resource itself was last modified. For example: `Last-Modified`: `Sun, 06 Nov 1994 08:49:37 GMT`. * `Varies` This header is included for user-specific headers (such as `Authorization`) in multi-tenant scenarios.