API Status & Policy

[#1]

• API Statuses
• Concept
• Controlled Available (CA)
• General Available (GA)
• Deprecated
• Life cycle policy
• Different types of changes
• Major releases
• Minor releases
• Announcing major releases
• Usage limits
• Spike arrest details

API Statuses

Concept

APIs with this status are still under development and the development team is still making changes. Only a sandbox is available to start testing and the API cannot be used with customer environments. 

Controlled Available (CA)

APIs (or API versions) with this status are not ready yet to be rolled out to the complete customer base:

• It is available to a few access partners

• Connections of an access partner to the customer environment (tenant) are put on a waiting list, and it will take time before the connection is accepted

• There can be functional limitations of these APIs

Controlled Available APIs have the usual security and support level.

General Available (GA)

APIs (or API versions) with this status are available to all access partners. The API can be used by all customers who use any of the HR Core systems that are supported by this API.

Deprecated

The API (or API version) is being phased out. We do not accept any new connections on this API (version). We will ask our access partners to move to another interface API. See also your Service Level Agreement

Life cycle policy

We aim to provide you with a policy for releases and support for older versions for a consistent and predictable experience.

You can also find this information in the Service Level Agreement.

Different types of changes

The life cycle of any API products has dependencies on underlying products. Changes in those products may require changes to the API to support it. We distinguish between breaking changes and non-breaking changes. A breaking change is one that breaks the contract an API consumer depends on, either by a change in structure, behavior or semantics. The release and support strategy makes a clear distinction in how these are managed.

Major releases

At times Raet may need to make larger changes to the API. Reasons may be changes to legal requirements, adding a large new feature to the API or an change in other products the API depends on. In these cases Raet may create a new major release of the API. We strive to also keep major releases backward compatible as much as possible but this may not always be possible. In case of breaking changes In general Raet aims to have a maximum of one major release per year.

Each major release will be supported for at least 24 months after releasing the next major version.

As a client to our API you will have to adjust your software to follow the major releases of our API as they will impact your integration. You must update your software to support the new API version as older API versions will be decommissioned following the policy as outlined above.

Minor releases

A minor release will never contain breaking changes, the are used to deliver incremental changes. Minor versions will not be visible in the path of the API. Raet can install minor updates in the standard release windows or as part of a hotfix and will communicate the changes as part of the release notes. Since this does not impact any existing functionality, we do not provide side-by-side support for multiple minor versions of the same major version: a minor upgrade just replaces the previous version.

As a consumer of the API it is up to you to decide if you start using the newly available features.

Announcing major releases

Each release of a major API version will be accompanied by communication about the support lifecycle of the current version in the release notes.

When approaching the sunset-date for an API product, we will actively reach out to inform any customers still using it:

Communication	When	Where	Recipient
Announcement	At the release of the new major version. Includes the date of decommissioning the previous version.	General release notes	All recipients of general release notes.
	At the release of the new major version. Includes the date of decommissioning the previous version.	Developer portal	Designated API contact persons
1st notification	6 months prior to decommissioning		Designated API contact persons
2nd notification	3 months prior to decommissioning		Designated API contact persons
3rd notification	1 months prior to decommissioning		Designated API contact persons

Usage limits

We apply usage limits to ensure the availability of our services to all parties interacting with Youforce. These usage limits depend on your subscription.

The following policies are determined per registered application:

	Weekly	Daily	Continuous
Quota - API calls*	2 hours per day 1000 API calls within the time window 7 days per month	2 hours per day 1000 API calls within the time window 40 times per month	6000 API calls per day, allowing to retrieve changes every 15 seconds
Quota - authentication calls	7 successful authentication calls per month.	40 successful authentication calls per month.	400 authentication calls per month
Concurrent rate-limiting (API calls in parallel)	1	1	3
Spike arrest policy (max number of API calls per minute)	100 calls per minute	100 calls per minute	100 calls per minute

*For the base API the limit is 100 calls per minute

Spike arrest details

Spike arrest is the way we protect against traffic spikes. Our APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy smooths the traffic to the general amounts.

Spike Arrest’s behavior differs from what you might expect to see from the literal per minute values.

Our default spike arrest is set to 100pm (100 requests per minute). That does not mean you can do 100 requests inside a 1-second. Spike Arrest smooths the number of full requests in a minute by dividing it into smaller intervals:

Per-minute rates get smoothed into full requests allowed in intervals of seconds.

For example, 100pm gets smoothed like this:
60 seconds (1 minute) / 100pm = 0.6-second intervals, or 1 request allowed every 0.6 seconds. A second request inside of 0.6 seconds will fail. Also, the 101st request within a minute will fail.

When you exceed the policy, the API will return response code '429 - Too many requests' and you have to wait for the next time window.