This page defines the guiding principles for our customers, business partners and developers working on API client implementation.

There are 3 rules for iWelcome APIs usage:

  1. Customer Client(s) of our APIs must accept increasing number of attributes;
  2. Bug fixes or payloads content changes resulting in version header change;
  3. 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@iwelcome.com",
    "firstname" : "Victor",
    "lastname" : "Boer"
}

Response:

{
    "id" : "50b88946-4663-11ea-b77f-2e728ce88125",
    "email": "victor.boer@iwelcome.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@iwelcome.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 iWelcome APIs. iWelcome 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@iwelcome.com",
    "firstname" : "Victor",
    "lastname" : "Boer",
    "dateOfBirth" : "3/12/1980"
}

Response:

{
    "id" : "50b88946-4663-11ea-b77f-2e728ce88125",
    "email": "victor.boer@iwelcome.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@iwelcome.com",
    "firstname" : "Victor",
    "middlename" : "de",
    "lastname" : "Boer",
    "dateOfBirth" : "3/12/1980"
}

Response:

{
    "id" : "50b88946-4663-11ea-b77f-2e728ce88125",
    "email": "victor.boer@iwelcome.com",
    "firstname" : "Victor",
    "middlename" : "de",
    "lastname" : "Boer",
    "dateOfBirth" : "3/12/1980"
}