abstract swish line in gradient colouring from pink to blue on a dark blue background

People First API

API Compatibility Considerations

The People First APIs are under continuous development and are constantly evolving as new functionality is developed. Wherever possible, changes to the current version of an API will be made in such a way as to maintain backward compatibility with existing consumers. Where this is not possible, a new version of the API will be created and the compatibility breaking changes incorporated into it (leaving the existing version unchanged). The mechanism for working with different API versions is detailed in the API Versioning section.

As an API consumer you need to be aware of the type of changes that are considered to be backwards compatible, and code your application to handle them. This applies to all People First APIs including the Domain APIs, OData APIs, and the Event Stream API.

The following changes are considered to still maintain backward compatibility and not require a new API version:

  • New resources (endpoints).
  • New HTTP methods on existing resources.
  • New attributes, links, or elements on existing data types within a resource.
  • New optional query parameters.
  • The support of new Content-Types in the body of responses (the use of that Content-Type having been indicated in the associated Accept request header).

API Versioning

People First APIs use a versioning scheme to allow clients to migrate smoothly to newer versions when new functionality is added to the People First product. The versioning scheme is based on an HTTP header named Api-Version. When this header is absent the request is treated as if it is requesting version 1 of the API. For later versions of APIs the Api-Version header must be supplied as per the example request below for a v2 API.

GET /api/v1/profile HTTP/1.1
Host: eu.peoplefirst.com
Authorization: Bearer ACCESS_TOKEN
Api-Version: 2

Where:

  • ACCESS_TOKEN is the access token supplied by your System Administrator, or ID token obtained separately (see:OIDC ID Tokens).

Note: The "v1" portion of the URI has no impact on the version of the API requested. This portion of the URI will be removed in the future.

When an API is superseded by a new version there will be a period of time where both old and new versions are supported in parallel to allow clients time to migrate to the newer version. Deprecation of APIs will be documented on this site and will also be communicated to customers to allow them fair notice to migrate.

Where APIs are documented without a version it should be assumed the API is available as version 1. Where versions later than 1 exist these will be explicitly documented.

Looking for something specific?