Forward compatibility guidance for PingOne client developers
This section provides guidance on what PingOne API client developers should do to maintain forward compatibility of their client applications as PingOne APIs evolve. PingOne is a continuously developing platform, and developers must be aware of non-breaking changes to the APIs and how to prepare for these inevitable changes. PingOne will rarely, if ever, introduce a breaking change; however, when that happens, there will be notifications or deprecation messages to inform developers. For non-breaking changes, client developers must ensure that their apps will function as expected after the following API changes occur.
Non-breaking API changes
Client applications should be resilient to additions of new optional properties in request, response, and event payloads. The following list of enhancements occur regularly to the Pingone platform API.
Related resource links
The addition of new related resource links added to responses should not cause application breaks in your client environments.
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"organization": {
"href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda"
},
"license": {
"href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda/licenses/3f06970a-3235-46cb-b46f-cf6dfee2bb84"
},Almost all PingOne API responses include a _links section that lists related resources as HAL (Hypertext Application Language) links, and these lists change as the platform adds new resources (and new relationships). For common endpoints, the list of HAL links changes often.
New optional properties
The addition of new (optional) properties added to request, response, and event payloads should not cause application breaks in your client environments.
PingOne API endpoints, even those that have been part of the platform since its inception, can receive additional optional data model properties as the platform matures. Client application developers must configure their client environments to accommodate new optional properties in requests and support new returned properties in endpoint responses.
|
The addition of a new required property is a breaking change that rarely, if ever, occurs in the platform. Endpoint deprecation occurs rarely. When this happens, it is accompanied by proper notification of the change, and the platform provides a designated period in which deprecated endpoint operations are supported after notification. For more information, refer to Protocol for breaking changes. |
New content-types or content-language formats
The addition of new content-types or content-language formats of the same resource should not cause application breaks in your client environments.
The platform API includes endpoints that support multiple content types. Client application developers must configure their application environments to accept supported media types for the endpoint. For example, the following request shows a new action on the /{{envID}}/flows/{{flowID}} endpoint that supports a device authorization grant. Your client environment should support the new content type, application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json.
curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json' \
--data-raw '{
"userCode": "{{userCode}}"
}In addition, the PingOne API might (over time) return new content types for a given resource. If a client is retrieving a resource without specifying the exact type that it is expecting, then it must be able to tolerate processing any response content type that satisfies the Accept HTTP header.
For example, a client issues this request:
curl --location --request GET '/some/resource' \
--header 'Accept: */*'Initially, GET /some/resource is represented by a Content-Type: application/json response, which satisfies the request’s Accept: /. A client could assume that this response is always application/json and only have code to process such responses.
However, at some later date, GET /some/resource supports a new Content-Type: text/html response, which also satisfies the request’s Accept: /. The platform does not guarantee the choice of Content-Type when multiple values satisfy the request. In such cases, the client could start receiving Content-Type: text/html and process this response incorrectly, expecting it to be JSON.
In cases where clients can receive any content type that satisfies their request’s Accept: / header, the client must be configured to handle any content type that is returned. Or, preferably, clients should be configured to be as specific as possible about the content type they are able to accept.
Case-insensitive request and response headers
It’s important that you do not treat request or response headers as case-sensitive. PingOne treats all request headers as case-insensitive, and may change the case of response headers at any time.
The HTTP 1.x and 2.x specifications require headers to be treated as case-insensitive.
New HTTP methods
The addition of new supported HTTP methods added to a resource should not cause application breaks in your client environments.
Client application developers must configure their application environments to accommodate new HTTP methods added to a platform service. For example, adding a new PATCH operation to an endpoint should be supported in your client environments.
Third-party libraries
Some third-party libraries deployed in your client environment can cause failures as a result of the non-breaking API changes listed above. In such cases, configuration of the library objects can resolve the issue.
For example, if your application environment uses the Jackson library to serialize or map Java objects to JSON, it is recommended that you update the object mapper setting responsible for deserializing API responses to prevent deserialization errors when new properties are added to the API response. The recommended setting is: new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);. (Jackson’s default setting is true.)
As a backup, you can also annotate Jackson library objects with the @JsonIgnoreProperties(ignoreUnknown = true) property to prevent deserialization errors. Conservative developers may choose to employ both strategies.
Protocol for breaking changes
Ping Identity will only support the current release of the platform APIs.
APIs and resources that are made generally available to all customers for Ping Identity’s multi-tenant hosted service products are designed to evolve in a non-breaking fashion rather than rely on versioning to change. In the case of a breaking change that requires an API or a resource to be versioned, the following describes the Ping Identity version support lifecycle:
-
The current version of the API or resource will be supported;
-
Once a new version of the API or resource is released, the previous version will also be supported for one (1) year; and
-
Anytime after this one (1) year period, previous versions of the API or resource will be removed.
|
Deprecated API responses contain the following two headers:
For example, |