Hi Kostas,
Thanks for drawing attention to this, I would love the developer community
to give input on this, so that we end up with a more acceptable product. I
would say the current status of the REST API is acceptable, and certainly
gives us the ability to do new things with DSpace. Its some of these finer
points that we will want to address so that we don't cause unnecessary
surprises, once this gets widely adopted. I think we still have time before
4.0 FINAL to make these final tweaks.
1) Versioning
I've been worrying about versioning for some time, and I'm mostly worried
that future updates to DSpace / DSpace-REST-API, when cause issues for
clients, so, versioning should be seen as mandatory. (i.e. This client was
designed to use v1.)
I'm in the school of thought that the version lives in the URI, and its on
the left-hand side of the base URI.
i.e. /rest/*v1*/collections, or /rest/*v2*/collections
Because I'm thinking that a future DSpace-REST could be reimplemented in
any technology, so requests to the old version, can be sent to an old
webapp still running. Or, you would have to build backwards compatibility
into new REST v2 webapp. Doing this at URI path, gives you plenty of tricks
to deal with it. Doing this in Headers, limits you to building a v2, that
can also speak v1.
Also, I'm thinking about weak/simple clients. i.e. single javascript file
that will embed a few Items on another site. They can set the URL, I'm
doubtful they will have very strong ability to customize every header.
Code to support multiple versions inside the API might look like:
@Path("/v1/myresource")
public class MyResource
@Path("/v2/myresource")
public class MyResourceV2
2) Response
I've been reviewing Anja's PR that includes a "context", such as
limit/offset/total-count. And I think it's also wrapping the response
objects in some type of named container.
https://github.com/peterdietz/DSpace/pull/2
I'm still reviewing it. The master-merge things cause some grief, but
there's plenty of good improvements in there.
2.iii) General / Template parsing.
For a moment I didn't return a collection, community, item, or bitstream
object, but it was instead the vanilla base-class of DSpaceObject. I like
the response to have the output object be wrapped in a "collection" or
"collections" object.
I'm not thinking of making anything like a WSDL. But we'll document the
format of the API when the release is final for 4.0, and then when 5.0 is
out, I'm guessing we'll have a REST v2 format emerging. When REST v2 is
ready we'll document the response objects. It might not kill us to create
some example code (I've got the Java Play! client app, and you've built
some ObjC iOS code). An SDK at some point might be useful, but I don't want
to get too far ahead of myself. I'm thinking something like that for Rails
or Javascript would be welcomed.
3) Better Error Messages
I would like to see friendly error messages, in some type of response
object. Throwing the HTTP status code is minimally acceptable, but an
"error" object, that said what went wrong, and not throwing a stack-trace
is definitely better. PR's wanted.
Peter Dietz
On Mon, Nov 4, 2013 at 4:52 AM, Andrea Bollini <a.boll...@cineca.it> wrote:
> 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
> listDspace-devel@lists.sourceforge.nethttps://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 525http://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
>
>
------------------------------------------------------------------------------
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
