API rules
This page defines the guiding principles for our customers, business partners, and developers working on API client implementation.
There are three rules for OneWelcome Identity Platform API usage:
- Customer clients of APIs must accept increasing number of attributes;
- Bug fixes or payload content changes resulting in version header change;
- Breaking changes (such as payload structure) resulting in an API endpoint 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 that 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
You use a client in a certain programming language or infrastructure component for OneWelcome Identity Platform APIs. The OneWelcome Identity Platform has the freedom to add extra attributes to a payload (in requests and responses). The client that you use must be able to accept these kinds 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"
}
