MLM API - employees endpoint - v1 vs v2

[#1]

Versions of the endpoint employees

For the endpoint GET /employees there’ll be 2 versions available (status : sep ‘20). These versions are ‘header based’ available for API consumers. 

The version is added to the header of the request:

Example requesting v2.0 using postman

The functional difference between those versions is the following :

V1 (DEPRECATED!)

In this endpoint version we face a small issue that an employee in core system HRCB (r1) becomes a single employee in our MLM API output. As a result that a single person is returned multiple times in our API’s (see example below).
Eventually this version will be phased out!

Person: {
 personID : 123,
 name : Jan Jansen,
 address : ABC,
 contract : A1,
 validFrom : 01-02-2020,
 validUntil : 10-04-2020
 }
Person: {
 personID : 123,
 name : Jan Jansen,
 address : DEF,
 contract : B1,
 validFrom : 11-04-2020,
 validUntil : 10-06-2020
 }
Person: {
 personID : 123,
 name : Jan Jansen,
 address : DEF,
 contract : B2,
 validFrom : 11-06-2020,
 validUntil : 31-12-9999
 }

V2

In this version V2 we’ve solved the above issue in V1, so we’ll return here in a correct way the current version of a unique person with the actual contract versions. We’ve included temporality on the ‘Person level' and also on the lower ‘Contracts level', so the API consumer is able to jump into conclusions very efficiently.

Scenario : standard exposure / current person versions with current contract versions

Person 1: { (current version)
 validFrom : 01-01-2020
 validUntil : 31-12-9999
 personID : 123,
 name : Jan Jansen,
 address : ABC,
 contract : A3, (current version)
 validFrom : 01-05-2020
 validUntil : 31-12-9999
 contract : B5 (current version)
 validFrom : 01-03-2020
 validUntil : 31-12-9999
 }
Person 2: { (current version)
 personID : 345,
 name : Joke van der Laan,
 address : HJK,
 contract : A2, (current version)
 contract : B2 (current version)
 }
……
Person 100 { (current version)
 personID : 964,
 name : Henk de Vries,
 address : VDW,
 contract : A1, (current version)
 contract : B4, (current version)
 contract : C1 (future version)
 contract C - version 1
 validFrom 01-10-2020
 
 
 --nextlink--

In the above V2 example we expose Person 1 with personId 123 who has two contracts (A, B). Each contract has its own versions. Contract A has two historical versions and one current version. Contract B has four historical versions and one current version.

Scenario : active person has only one historical inactive contract

The following scenario covers again Person 832 who’s having just one contract (A) which became historical (since yesterday). The endpoint will return his actual personal details with this (historical) contract data.
So in case, there is no active contract, the response will show the last active contract version (latest historical).

Person 72: { (current version)
 personID : 832,
 name : Piet van de Berg,
 address : DDS,
 contract : A3 (historical version)

Scenario : active person is a ‘new hire’ with one future contract

In the below scenario of Person 193, who’s having just one future contract (future hire). The /employee endpoint return actual person details with his contract details.
Since there is no active contract, it will return the future contract version.

Person 41: { (current version)
 personID : 193,
 name : John de Jong,
 address : HJA,
 contract : A1 (future version)