Standard API Rules
This page defines the guiding principles for our customers, business partners and developers working on API client implementation.
There are 3 rules for OneWelcome APIs usage:
- Customer Client(s) of our APIs must accept increasing number of attributes;
- Bug fixes or payloads content changes resulting in version header change;
- Breaking changes (e.g. payload structure) resulting in an API endpoint(s) version change.
Example: accept increasing number of attributes
If we change the structure of a payload of an existing API, we change the version of the API. This means that the URL changes from v1 to v2
<api-name>/v1/<resource> to <api-name>/v2/<resource>
POST <api-name>/v1/<resource>
{ "email": "victor.boer@onewelcome.com", "firstname" : "Victor", "lastname" : "Boer"}Response:
{ "id" : "50b88946-4663-11ea-b77f-2e728ce88125", "email": "victor.boer@onewelcome.com", "firstname" : "Victor", "lastname" : "Boer", "dateOfBirth" : "3/12/1980"}Example: content changes resulting in version header change
Let's assume we have an API that produces a payload which contains a date value. Because of some requirement the format of this attribute value changes. For this change we can use the Accept header. The first version of the API works with the Accept header equals to Accept: application/vnd.iwelcome.v1+json, the changed implementation uses Accept: application/vnd.iwelcome.v2+json".
POST <api-name>/v1/<resource>
Header: "Accept: application/vnd.iwelcome.v2+json"{ "email": "victor.boer@iwelcome.com", "name" : { "firstname" : "Victor", "middlename" : "de", "lastname" : "Boer" }, "dateOfBirth" : "03121980"}Response:
{ "id" : "50b88946-4663-11ea-b77f-2e728ce88125", "email": "victor.boer@onewelcome.com", "name" : { "firstname" : "Victor", "middlename" : "de", "lastname" : "Boer" }, "dateOfBirth" : "03121980"}Example: breaking changes
Customer uses a Client in a certain programming language or infrastructure component for OneWelcome APIs. OneWelcome has the freedom to add extra attributes to a payload (in requests and responses). The Client used by the customer must be able to accept these kind of changes.
The current version supports only firstname and lastname:
POST <api-name>/v1/<resource>
Header: "Accept: application/vnd.iwelcome.v1+json"{ "email": "victor.boer@onewelcome.com", "firstname" : "Victor", "lastname" : "Boer", "dateOfBirth" : "3/12/1980"}Response:
{ "id" : "50b88946-4663-11ea-b77f-2e728ce88125", "email": "victor.boer@onewelcome.com", "firstname" : "Victor", "lastname" : "Boer", "dateOfBirth" : "3/12/1980"}Change of payload, but not changing any version (adding middlename only):
POST <api-name>/v1/<resource>
Header: "Accept: application/vnd.iwelcome.v1+json"{ "email": "victor.boer@onewelcome.com", "firstname" : "Victor", "middlename" : "de", "lastname" : "Boer", "dateOfBirth" : "3/12/1980"}Response:
{ "id" : "50b88946-4663-11ea-b77f-2e728ce88125", "email": "victor.boer@onewelcome.com", "firstname" : "Victor", "middlename" : "de", "lastname" : "Boer", "dateOfBirth" : "3/12/1980"}