API Design - HTTP Date Header (RFC 822) with ISO Date/Time formats.

[MendeleyStack]

We can't be the first person to stumble across this API design issue. 

HTTP defines its own date format (RFC 822), whereas we want to use ISO 8601 as much as possible in the API.  The problem areas come when we want a client to supply a date in ISO 8601 format, but we've been forced to give it to them in the very grotty RFC 822.  Options for getting around this include:

• do nothing - clients have to do a slightly painful thing.
  
• do nothing, but aid clients by providing a microservice that converts one date format to another.
• return the ISO 8601 date in a (custom) header.
• return the link that should be used for the next sync in a Link header, with the date correctly formatted for the client to use (background explanation below)
• accept RFC 822 dates as well as ISO 8601 dates on the API (but only return ISO 8601).

Background Context to explain the sync remark:

Our APIs provide access to some large collections (documents, files, ...) which change fairly infrequently.  Clients may want to stay up to date with the latest changes, without having to download the full collection every time.  It's possible to do this by combining standard API operations - here's how.

Given a request like:

GET /documents

Host: mix.mendeley.com

Accept: application/vnd.mendeley-document.1+json

The server responds

200 OK

Content-Type: application/vnd.mendeley-document.1+json

Date: Thu, 24 Apr 2014 16:38:02 GMT

Link: <https://mix.mendeley.com/documents?marker=00000000-0000-0001-0000-000000000002&limit=20>; rel="next";

 

[

  .. documents

]

The client should take note of the date header from this first page - this is the time on the server that the sync started.  It should then follow the link to get the next page.

[Darrel Miller]

Joyce,

Here are a few thoughts.

Most decent client libraries should deal with the nasty date format
and provide the conversion to a native datetime format.

A custom header is definitely an option, however, would it not be
worth adding a "SyncDateTime" property to the returned json
representation. The Date header on the HTTP response is the time at
which the representation was generated. That isn't necessarily the
same time as the "SyncDateTime". Your currently implementation may
enforce that, but will it always be that?
You suggest that the client should "take note of the date...". If the
date was embedded in the returned payload, then the client would
automatically get a copy of that date when it parses the payload. The
date and the list of documents would be naturally attached together on
the client, rather the client having to keep track of which date
belongs to which array of documents.

I'm not sure I fully understand the suggestion to embed the date in
the link header. You don't want the client to have to start parsing a
URI to pull data out of it, if that is what you are considering.

You talk about accepting dates in your API, but I don't see where you
are doing that. I would certainly only use the ISO 8601 date format
for parameters and body content. The RFC 822 dates are an artifact of
history that we just can't change without breaking a whole lot of
stuff. I would never voluntarily choose to use them.

Anyway, just my thoughts on the subject.

Darrel

> --
> 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 http://groups.google.com/group/api-craft.
> For more options, visit https://groups.google.com/d/optout.