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
• 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.

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, behaviour or semantics. The release and support strategy makes a clear distinction in how these are managed.

Major releases

At times Visma YouServe 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 Visma YouServe 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 Visma YouServe aims to have a maximum of one major release per year.

Each major release will be supported for at least 12 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. Visma YouServe 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 community	Users of the Develope community
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

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 behaviour 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.