Dear developers,
I have some comments, regarding the Jersey Rest API, after a discussion we
had with Peter Dietz in the "dspace" IRC channel some days ago.
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.
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:
i) Other metadata can be inserted in the response, like the request params,
the api version, the response time of the server (and I guess others as
well)
ii) It helps the backward compatibility, since the response can change in
the future by adding new metadata in it, but clients can still operate
correctly. As it is now, any addition (apart from within the actual
response) will break any client.
iii) Clients can benefit from having a general parser to parse the template
and more specific ones to parse the actual response.
Again, we would like to hear your opinion on that.
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.
Best regards,
Kostas Stamatis
[1] <http://barelyenough.org/blog/2008/05/versioning-rest-web-services/>
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
[2]
<http://barelyenough.org/blog/2008/05/versioning-rest-web-services-tricks-an
d-tips/>
http://barelyenough.org/blog/2008/05/versioning-rest-web-services-tricks-and
-tips/
[3]
<http://jersey.576304.n2.nabble.com/Restful-Service-Versioning-td6332833.htm
l>
http://jersey.576304.n2.nabble.com/Restful-Service-Versioning-td6332833.html
[4]
<http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
/6750376#6750376>
http://stackoverflow.com/questions/389169/best-practices-for-api-versioning/
6750376#6750376
------------------------------------------------------------------------------
Android is increasing in popularity, but the open development platform that
developers love is also attractive to malware creators. Download this white
paper to learn more about secure code signing practices that can help keep
Android apps secure.
http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk
_______________________________________________
Dspace-devel mailing list
Dspace-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/dspace-devel
