Time, content types and showing the developer (and user) what's possible (HATEOAS)...
Time
Using UNIX time may be easier for a developer, and I do concede that point, but by using UNIX time you're doing a few things:
1) You're exposing some internal logic or data structure of the system in the resource
2) You're removing information on time zone
3) In some circumstances where greater precision is needed you're precluding the use of nanoseconds
I know that some languages don't naturally handle ISO8601 dates with nanoseconds, but I do think that's the best format.
YYYY-MM-DDTHH24:MI:SS.NNNNNNNNNZ
With that format one can keep a deeper knowledge of timezone, of precision, of human readability (and JSON.org does say that JSON is easy for humans to read).
Content Types
Whilst it may be pragmatic to not plumb the depths of custom content types they should at least be mentioned and made compulsory even if they aren't typed to a detailed level of specificity. Content Type: application/json is fine, so long as it's used and paid attention to.
Capabilities
HATEOAS and meta-data... I like to encourage developers to explore what's possible in the API by showing them the actions that they can do on an item, and their permissions. As in... if they can update something, show them how by telling them the URL. The API should ideally not lead a developer to an action that they couldn't perform.
Minor Points
I generally prefer to restrict the possible HTTP status codes and publishing that list so that a developer implementing against the API can build a generic wrapper, know what to expect and take care of handling it. Which means, sometimes I will generalise a response rather than using a status code in one place and one place only.
I'm not so sure on using verbs for special actions like search, 'q' is a well understood part of the 'query string', and I'd make that just an optional parameter on the pluralised collection URL. But... perhaps that's just a bad example.
> 1) You're exposing some internal logic or data structure of the system in the resource
Not following. What internal logic or data structure?
> 2) You're removing information on time zone
This is [almost] always a good thing. Obviously there's personal preference involved here, but I've never seen a system where storing the TZ turned out to be a good idea (not that I've seen all that many systems).
> This is [almost] always a good thing. Obviously there's personal preference involved here, but I've never seen a system where storing the TZ turned out to be a good idea (not that I've seen all that many systems).
Assuming that time is important, perhaps Google Calendar is a good example of timezones and datetimes as strings:
I guess it depends on what you're doing with the data... if it's just "created" then it matters less. But if you're dealing with storing an event in time, it usually occurs in a place that has timezone data... boarding a plane in one timezone and landing in another, a meeting where attendees dial-in from multiple timezones and you need to alert them all at the right time and visually indicate that.
Timezones aren't trivial, and the system might store UTC under the hood, but throwing them out universally and trusting every client to get it right seems less of a good idea than handling them and taking care of that on the API side.
It looks to me like you can set what TZ you want to retrieve dates in when performing queries, with the default being the TZ associated with the calender; this is substantially different than simply returning times with whatever arbitrary TZ was used when creating the record.
Any process that involves date/times and doesn't involve date/times being stored and processed as UTC dates is the wrong solution. As the final step on the presentation layer you can convert them into whatever wacky TZ you want but passing dates back and forward to the server in non-UTC format is fast track to Insanityland
But I would go further and suggest that whether to show those shouldn't just be based on what the API can do, but what the client (and perhaps user controlling the client) can do.
As in... if they can read but not create, then show the "self" link but not the "newcomment" link.
Thus we're not just saying "our API has these endpoints", we're saying "you can do this".
> With REST, the URL for a resource never changes.
I could have an endpoint example.com/users become example.com/subsite/users. It is precisely because the URL might change that you want to give the client URLs to the next possible actions.
First, yes, you could change your "endpoint" URL, but that's not the reason for providing URLs in HATEOAS (just for the record, I hate(oas) that acronym).
You see, REST is different from most other Web services because it doesn't provide access to actions, but to resources. It can be compared to the good old SQL database -- and a resource's URL is the way to uniquely identify that resource, just like in a RDB you would have a combination of a table and a unique identifier.
The reason for providing URLs is to free the consumer from having to construct it by hand each time. In fact, an URL can change -- but not an URL to a single resource (just like you wouldn't arbitrary change a RDB record's ID); rather, a completely different resource can be provided instead.
I misused "action". Replace "to give the client URLs to the next possible actions." with "to give the client URLs so they can perform their next possible actions on related resources".
My point remains: one of the main reasons of using HATEOAS is so that you can evolve your API without breaking clients. The other main benefit is so that your client can discover your protocol by simply following hypermedia controls.
A RESTful API, in its original understanding as defined by Roy Fielding, is based on hypertext (links between resources), content types and traversal: the only "official" URI in the system (the only one which should be documented and immutable) is that of the API's root. For all other API components, the only supported access method is traversing the system until the component is reached.
As a result, there is no requirement either of URI beauty or of URI stability in a RESTful system: clients may cache URIs during traversal to speed-up subsequent operations (think bookmarks) but that's only an optional optimisation and they must know how to re-traverse the system anyway.
Stable and beautiful URIs are "cooler", but they're irrelevant to the system's RESTfulness and a correctly RESTful system (server & client) would allow randomly changing all URIs in the system (but for the root) regularly without functional breakage.
Time
Using UNIX time may be easier for a developer, and I do concede that point, but by using UNIX time you're doing a few things:
1) You're exposing some internal logic or data structure of the system in the resource
2) You're removing information on time zone
3) In some circumstances where greater precision is needed you're precluding the use of nanoseconds
I know that some languages don't naturally handle ISO8601 dates with nanoseconds, but I do think that's the best format.
YYYY-MM-DDTHH24:MI:SS.NNNNNNNNNZ
With that format one can keep a deeper knowledge of timezone, of precision, of human readability (and JSON.org does say that JSON is easy for humans to read).
Content Types
Whilst it may be pragmatic to not plumb the depths of custom content types they should at least be mentioned and made compulsory even if they aren't typed to a detailed level of specificity. Content Type: application/json is fine, so long as it's used and paid attention to.
Capabilities
HATEOAS and meta-data... I like to encourage developers to explore what's possible in the API by showing them the actions that they can do on an item, and their permissions. As in... if they can update something, show them how by telling them the URL. The API should ideally not lead a developer to an action that they couldn't perform.
Minor Points
I generally prefer to restrict the possible HTTP status codes and publishing that list so that a developer implementing against the API can build a generic wrapper, know what to expect and take care of handling it. Which means, sometimes I will generalise a response rather than using a status code in one place and one place only.
I'm not so sure on using verbs for special actions like search, 'q' is a well understood part of the 'query string', and I'd make that just an optional parameter on the pluralised collection URL. But... perhaps that's just a bad example.