Hi,
On 4 November 2013 09:13, Kostas Stamatis <kstama...@ekt.gr> wrote:
> 1) REST API versioning
>
> ---------------------------
>
> As read from some sites and blogs, the versioning of a REST API can be
> denoted either in the URL or in the mime type of the HTTP communication (in
> the ”Accept” and “Content-Type” header fields).
>
> ex1: http://example.dspace.com/rest/v1/communities
>
> ex2:
>
> ===>
>
> GET /communities HTTP/1.1
>
> Accept: application/vnd.dspace.rest-v1+json
>
> <===
>
> HTTP/1.1 200 OK
>
> Content-Type: application/vnd.dspace.rest-v1+json
>
>
>
> Either has advantages and disadvantages, as I read. For example, the
> former is said to be wrong since the same resource may have more than one
> URIs pointing to it. The latter helps the backward compatibility. From what
> I read, I think that most preferable is the second method.
>
>
>
> [1], [2]. [3] and [4] are for reference.
>
>
>
> We would like to hear your opinion on that.
>
The latter doesn't really help backward compatibility - it possibly saves
you having to update which URLs you call, but you still have to ensure that
you are passing a supported "accept" header, and dealing with the response
appropriately. What happens if the API gets updated and no longer supports
what you are passing as an accept header - does it give an error? Does it
attempt to work, and then go horribly wrong?
And what happens if you don't pass an accept header?
Too many potential problems with encoding version within the accept header.
The URLs should have a version as part of their path, and we should try to
maintain compatibility as far as possible. By which I mean we should be
able to introduce non-breaking extensions onto an existing API version in
later releases, without having new version URLs, and even when we introduce
new version URLs, we should maintain existing URLs as far as is reasonably
possible.
Note that content negotiation (use of the "accept" header) is still
reasonable on those URLs, so that we can request XML serializations, JSON
serializations, etc. from the same URL - possibly even request different
JSON serializations (e.g. may have more or less data - could be useful for
performance reasons). But this should follow the standard HTTP content
negotiation specification.
> 2) REST API responses
>
> ---------------------------
>
> I had the chance to play around with the REST API the previous days. What
> I noticed is the heterogeneity of the responses. “communities” JSON
> endpoint returns an array while the “communities/{id}” endpoint returns a
> map. I would expect, all the responses to return the same response template
> within which someone can find the actual response. Something like the real
> response being wrapped around another object that has other fields as well.
> This template has the following pros:
>
There should be consistency in the responses as far as is reasonable -
taking into account what type of resource(s) you are dealing with for. For
instance, I would expect that a call to "/communities" would result in a
list / hierarchy of all communities (or just the ones at the top level),
whereas calling "/communities/{id}" would result in information about that
specific community.
Of course, this is complicated by dealing with things like do you return
sub-communities and collections? One approach might be to have
"/communities/{id}/info" returning just information about that community,
and "/communities/{id}/communities" the hierarchy of sub-communities and
collections (which would then be represented the same as "/communities").
The API should be designed around efficiency both in returning the maximum
amount of useful information in the minimum number of calls, and being able
to provide minimal amounts of data in a call where that is more appropriate.
> 3) REST API error responses
>
> ----------------------------------
>
>
>
> At this time, errors are returned as HTTP status errors which is fine.
>
> There is also the option (not implemented yet) errors to be returned as
> part of a valid response. That is, the aforementioned template could
> include metadata about the status of the response, the error code (if
> exists) and a localized message. Of course, HTTP status errors, in some
> cases, could also apply.
>
> When the error is embedded in the response, the actual error problem could
> be sent to the user instead of just an HTTP error code.
>
>
>
> Once again… we need you opinion here as well.
>
HTTP statuses are a minimum useful set, which we should encourage the
intelligent use of. But where possible we should enhance this by returning
detailed information in the response as well.
G
------------------------------------------------------------------------------
November Webinars for C, C++, Fortran Developers
Accelerate application performance with scalable programming models. Explore
techniques for threading, error checking, porting, and tuning. Get the most
from the latest Intel processors and coprocessors. See abstracts and register
http://pubads.g.doubleclick.net/gampad/clk?id=60136231&iu=/4140/ostg.clktrk
_______________________________________________
Dspace-devel mailing list
Dspace-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/dspace-devel
