First, I wanted to thank (especially) Peter, Anja, Kostas, and several others
for reinvigorating the work around a REST API.
Even though I've been too busy to comment until now, I'm interested and did
note the progress. I do have some observations/impressions, which follow in no
particular order.
* I think it's great to have a central 'rallying point' in our codebase for
this work, but I *don't* think the fact that we are about to ship 4.0 means
that we should lock down the API, functionality, etc. In my mind there is
plenty of room to mature/elaborate it, and we don't want to foreclose those
possibilities. As long as the DSpace internal API doesn't change, the REST code
could evolve and be redeployed (after all, it is not like a UI - end-users
won't be consuming it directly. Rather, tool or UI developers will be building
things *against* it, and they can manage redeployments).
* I think it's a clear win to utilize JAX-RS: it has greatly reduced
implementation complexity and for me at least is much easier to follow.
* I won't weigh in yet on the URI-based vs versioned/vendor media type for API
versioning: there are a lot of considerations and 'religious' positions taken.
I'm of the opinion that we should concentrate first on the basics, and these
can be addressed in time.
* The endpoint selections and their URI syntax raises some questions for me.
Specifically, I'm not wild about DB keys as resource identifiers - they are
actually somewhat fragile.
Persistent IDs such as handles might be a better choice (see detailed example
below).
* Even though we are not yet paginating results, or doing updates in addition
to reads, thinking about those use cases can have implications on the resources
and their names.
To illustrate these last few points, I will briefly describe a REST API I'm
working on in mds (also JAX-RS based), which is close enough to DSpace for
these purposes.
It has a sort of 'meta-model' that utilizes 2 kinds of resources:
'Enitity' : DSpace Objects, like Communities, Collections, Items, Bitstreams
'EntityRef Lists' : lists (sets) of Entity references (that can be paginated)
So here's what the resource URI map (endpoints) looks like, and some responses
(the URIs start with 'content', since the REST API also deals with other types
of resources, 'admin', 'curation', etc):
http://localhost:8080/webapi/content/roots <-- a resource that represents the
'roots' of the content hierarchy (= top level communities), so is an EntityRef
List:
(response in XML)
<entityRefs>
<entityRef>
<name>DSpace History</name>
<URI>
http://localhost:8080/webapi/content/community/123456789/1
</URI>
</entityRef>
</entityRefs>
http://localhost:8080/webapi/content/community/123456789/1 <-- a community
resource, which is an Entity:
(response in XML, abbreviated)
<community>
<name>DSpace History</name>
<handle>http://hdl.handle.net/123456789/1</handle>
<collections>
http://localhost:8080/webapi/content/community/123456789/1/collections
</collections>
<subcommunities>
http://localhost:8080/webapi/content/community/123456789/1/subcommunities
</subcommunities>
<URI>
http://localhost:8080/webapi/content/community/123456789/1
</URI>
</community>
Note that the 'collections' element is not the list of collections, but a
*resource* that is the list (and so can be paginated if large).
The rest of the URIs are fairly predictable:
http://localhost:8080/webapi/content/collection/123456789/2 <-- a collection
resource, an Entity
http://localhost:8080/webapi/content/item/123456789/3 <-- an item resource,
Entity
http://localhost:8080/webapi/content/bitstream/123456789/3/1 <-- a bitstream
resource, Entity (sequence number last part)
http://localhost:8080/webapi/content/bitstream/123456789/3/1/foo.jpg <-- the
bitstream media object (ie. the bits)
Having separate resources for collection lists, etc has not just the benefit of
paging, but it also enables natural REST operations/semantics on adding
collections (POST to that 'collections' URI, etc)
I've got more (including some of the issues raised by Kostas), but wanted to
contribute to the discussion, and acknowledge all the good work so far.
Thanks,
Richard
------------------------------------------------------------------------------
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
