Follow @bissell
Michael's blog
Michael's resume

The API Contract
Default Formats
General API Management
Error Standards
Response Codes
Cherry Picking
Change Logs

Change Logs

RESTful APIs are, by design, stateless. But there are times that we require an audit trail or the need to roll back to a previous version. To accommodate this we add a

If we have an object like this:
{ "peopleId": "ed0e7d00-31b3-433d-90a1-c14a97920488", "userName": "somebody@somewhere.ext", "firstName": "Some", "lastName": "Body", "emailAddress": [ { "email": "somebody@somewhere.ext", "verified": "verified", "source": "ORCHIS" } ], "agencyCode": [ "584" ], "modified": "1477942735", "created": "1477942735" }
and we do a PUT to update her first name:
PUT /people/ed0e7d00-31b3-433d-90a1-c14a97920488 { "peopleId": "ed0e7d00-31b3-433d-90a1-c14a97920488", "userName": "somebody@somewhere.ext", "firstName": "Newname", "lastName": "Body", "emailAddress": [ { "email": "somebody@somewhere.ext", "verified": "verified", "source": "ORCHIS" } ], "agencyCode": [ "584" ] }
The API responds normally with a 200 OK at the payload, but it also creates a second object in /people/changelog:
{ "peopleId": "ed0e7d00-31b3-433d-90a1-c14a97920488", "firstName": "Newname", "modified" : 1515696314, "applicationId" : "e9273cc631e21b85ffb6df84ea8bd1c3" }
Where the modified timestamp is the server generated time the change was made to the people object 57a27db8e4b0822ebccb4ae0 and the applicationId is the app that executed the PUT.

The changelog should be available two ways:

GET /people/changelog
(Return an array of all changes)

GET /people/ed0e7d00-31b3-433d-90a1-c14a97920488/changelog
(Convenience for /people/changelog?peopleId=ed0e7d00-31b3-433d-90a1-c14a97920488)

Deletions should set a flag to is Deleted in the source document and create a simple response showing the is deleted flag:
{ "peopleId": "ed0e7d00-31b3-433d-90a1-c14a97920488", "isDeleted": "Y", "modified" : 1515696314, "applicationId" : "e9273cc631e21b85ffb6df84ea8bd1c3" }
Arrays will need to show the entire, new, array.

Be sure to see my blog over at Cloudenity. This week's topic: Identity Isn't Just for Users Anymore