Hi Kostas,
here my viewpoint
1) I prefer the header method. A missing header should be read as the
current version.
2) I agree with you. It is usually to find a common template across REST
API implementation and we should follow the "common practice"
3) Detailed errors information are desirable so also in this case, I
agree with you about the opportunity to introduce a response error object
Andrea
Il 04/11/2013 10.13, Kostas Stamatis ha scritto:
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/
[2]
http://barelyenough.org/blog/2008/05/versioning-rest-web-services-tricks-and-tips/
[3]
http://jersey.576304.n2.nabble.com/Restful-Service-Versioning-td6332833.html
[4]
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
--
Andrea Bollini
Dipartimento Servizi e Soluzioni per l'Amministrazione Universitaria
Divisione Ricerca
Via dei Tizii, 6
00185 Roma, Italy
tel. +39 06 44 486 087 - mob. +39 348 82 77 525
http://www.cineca.it
------------------------------------------------------------------------------
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
