Way to get history of a resource

[Nicolas Faugout]

Hi.

We have lots of REST APIs, but we never had the need to retrieve the state of a resource at a certain point in time.

Imagine we have a "user" resource, with a "legalEntity" and "department" properties.

If I want the current values, I can just do :

GET /api/users?fields=id,name,legalEntity,department

With the log history, I can rebuild the history of a specific property for a specific user :

GET /api/users/123/logs?propertyName=legalEntity&orderby=createdAt,asc

But what if I want a snapshot of the user at a specific point in time. Should I handle something like this :

GET /api/users/123?asOf=2016-01-01T10:00:00.000 ?

I have found several example saying I should use versions, but what I don't like with versions of a resource is that you have to know in advance which version number you should query, and that version number is not directly related to time.

In other words, how to represent a way of querying temporal data ?

Thanks in advance,

Nicolas.

Nicolas Faugout Associé, responsable R&D 24 rue du Champ de l'Alouette 75013 Paris - France Standard : +33 (0)1 83 64 53 20

Retrouvez l'actualité des métiers administratifs et RH sur notre magazine

[Gopi Suvanam]

There could be several ways to implement this. Such use cases are very common in financial data APIs. The most popular way is to explicitly have a parameter for date (asOfDate or startDate  & endDate).. you can have look at these two popular API documentations:

http://www.xignite.com/forex/api/GetHistoricalRate

https://data.oecd.org/api/sdmx-json-documentation/#d.en.330346

In the first case they use two different URIs for live data and historic data. In the second case same URI is provided with optional date parameter..

Cheers

Gopi

[Lukas Rosenstock]

Hello Nicolas,

from an API URL design standpoint I think using a query parameter such as ‚asOf' is a valid approach.

For an API consumer using a date is obviously the easiest way of accessing historical data. I would still recommend keeping a version number and allow querying using that number, too. But mainly it depends on the use cases which you want to implement. What kind of questions will API consumers ask? What is their need to access historical data? If you start from those it can make it easier to find the right kind of API - API design starts here.

Regards,

Lukas Rosenstock

https://cloudobjects.io/

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Chris Mullins]

Querying temporal data isn't quite what you are doing. Temporal data is more complicated than you think - if you're bored and looking for a decent overview of temporal data modeling and querying, you can start here. 

Fortunately, what you're doing is is querying a log, which is much easier. :) 

The question, really, is what your API Consumers will expect. If it's "Give me the value of AAPL Stock on Dec 31, 2014" then, the "asOf" approach works well. If it's "Give me the values of APPL Stock between Jan 1 and Jan30 2015" then it's the "startDateTime / EndDateTime" approach. If it's "gimme version 2" then just "/{resource}?historicalVersion=2. 

If there are very few versions, you can punt the work to the callers and always give back "all", although this would stink as a Dev experience. You could also do "?gimmeLast=3" to get the most recent 3 values... 

You could do the "orderBy" / ascending / decending / take / skip thing, which would also let do you what you want. 

In short - just do what's easiest for your callers. I think they're all about equally complex on the server side. 

Cheers,

Chris