Implementation of the API in Reptor

27 Feb 2017

Dear all,
I'm working already for some time on a repository software which
implements some of the RDA recommendations (DFT, DTR etc.). So I moved
the "standalone" implementation of the API I did so far into the
"Reptor" software.
I installed an empty instance of Reptor for playing around with the
collection API. Feel free to kill it :-) :
http://reptor.thomas-zastrow.de/col-wg/index.php
-> There is an example folder "photos" which shows most of the
functionality, including the collections. Metadata, PIDs, object data
etc. can be edited from the "admin" interface, on the top.
How collections are working:
- Collections are integral part of the Digital Objects in Reptor: any DO
can contain a collection with any kind of items. Collections are handled
as a kind of metadata
- The name / ID of a collection is the path to it. Any DO can have one
or more PIDs, so that PID could be also used to adress the collection
(Part Identifiers? Still some things to think about)
- In this instance, all "write" operations are protected by the Apache,
"GET" requests are not secured. You can use the user "reptor" with
password "rda" for executing write actions to the API
- The same user can be used for the "admin" interface
- The collections API is located in "collections/api.php"
So here are the six commands of the collections API which I implemented
as a minimum (and yes, they are giving back nice Json output):
Getting a list of all collections:
curl -X GET
http://reptor.thomas-zastrow.de/col-wg/collections/api.php/collections
-----------
Creating a new collection in the DO "demo". If DO "demo" does not exist,
it will be also created:
curl -u reptor:rda -X POST
http://reptor.thomas-zastrow.de/col-wg/collections/api.php/collections/demo
(On the startpage, there is now a new subfolder "demo" which is nearly
empty. Via the admin interface, you can add other kinds of metadata,
PID, object data).
-----------
Lets add two items to the collection in "demo":
curl -u reptor:rda -X POST -d '{"id" : "My first item"}'
http://reptor.thomas-zastrow.de/col-wg/collections/api.php/collections/d...
curl -u reptor:rda -X POST -d '{"id" : "One more item"}'
http://reptor.thomas-zastrow.de/col-wg/collections/api.php/collections/d...
-----------
List all members of a collection:
curl -X GET
http://reptor.thomas-zastrow.de/col-wg/collections/api.php/collections/d...
-----------
Deleting a member of a collection (URL encoded string necessary):
curl -u reptor:rda -X DELETE
http://reptor.thomas-zastrow.de/col-wg/collections/api.php/collections/d...
-----------
Delete the whole collection in "demo" (this will NOT delete the DO):
curl -u reptor:rda -X DELETE
http://reptor.thomas-zastrow.de/col-wg/collections/api.php/collections/demo
Best,
Tom
P.S.: Theres only a small chance that I will participate in the VM
tomorrow. Have a nice meeting!

  • Bridget Almas's picture

    Author: Bridget Almas

    Date: 28 Feb, 2017

    Hi Thomas,
    This is great -- thanks for doing it!
    A couple of questions:
    1) do you plan to implement the full collection model schema for the
    requests? I note that if I add an item to a collection like
    |{ "id": "string", "capabilities": { "isOrdered": false, "appendsToEnd":
    true, "supportsRoles": false, "membershipIsMutable": true,
    "metadataIsMutable": true, "restrictedToType": "string", "maxLength": -1
    }, "properties": { "ownership": "string", "license": "string",
    "modelType": "string", "hasAccessRestrictions": false, "memberOf": [],
    "descriptionOntology": "string" }, "description": {} }|
    It accepts it but just ignores everything except the id and when I
    retrieve the members that information is not present.
    2) I think the success messages are interesting. The current spec calls
    for an empty response body and an HTTP status code for most success
    responses, but I see the point of having a readable response and think
    maybe we need to consider adding that to the spec. What do others think?
    3) Can you add your implementation code to the RDA Collections WG GitHub
    repository?
    Best
    Bridget

  • Thomas Zastrow's picture

    Author: Thomas Zastrow

    Date: 28 Feb, 2017

    Hi Bridget,
    Thanks a lot, let me answer your questions:
    1.)
    No, I will not implement the whole schema. From my point of view, the
    six methods I implemented so far are the basic and minimum functionality
    an implementation of the collection API would need. For these, only an
    ID is necessary, all the other information can be optional. In that
    respect, my implementation represents the minimum someone has to implement.
    But as you may have seen - in Reptor, the collection functionality is
    embedded in a Digital Object. And some of the properties of that DO can
    be seen as "inherited" also to the collection itself, for example all
    the other metadata in Dublin Core format etc. Its a policy question.
    And its Open Source, so if someone else is interested ... feel free to
    do so :-)
    2.)
    I think it is necessary to give back some more information - for
    example, if creating a collection fails, it would be nice to get the
    reason for this ("collection exists already" or whatever).
    3.)
    No, because it is integral part of the Reptor software - which is of
    course also OpenSource and available on GitHub:
    https://github.com/TomZastrow/reptor
    For example, you can see the collection in Reptors interface:
    http://reptor.thomas-zastrow.de/col-wg/index.php?path=/demo
    And the collection can also be manipulated manually via the admin
    interface, so the collections API implementation code makes not much
    sense outside the rest of the Reptor software.
    I wish you a nice meeting later,
    Tom

  • Tobias Weigel's picture

    Author: Tobias Weigel

    Date: 28 Feb, 2017

    Hello Tom, all,
    I believe one important item we have to clarify is what exactly the
    minimal set of operations should be that an API endpoint must provide in
    order to be considered compliant with the Collections API specification.
    I understand that we already have quite a bit of flexibility and
    compromise in the depth of features an endpoint can provide, and this is
    described in machine-friendly way through the /capabilities response.
    But I also feel that we should not decrease the 'core' set of features
    too much as it would seriously diminish the value of the specification
    for interoperability.
    I am currently considering the following methods to be mandatory -
    mostly everything except for collection ops:
    GET, POST /collections
    GET, PUT, DELETE /collections/{id}
    GET /collections/{id}/capabilities
    GET, POST /collections/{id}/members
    GET, PUT, DELETE /collections/{id}/members/{mid}
    GET, PUT, DELETE /collections/{id}/members/{mid}/properties/{property}
    Then, there is also details to be specified for the capabilities and
    properties; for most of them, we already have default values, and I
    think that a compliant endpoint should provide them. I am uncertain
    currently whether we have already talked about this, but I believe that
    only a very few of the values are optional; and if they are, we should
    mark them as 'optional' in the spec.
    Best, Tobias

  • Thomas Zastrow's picture

    Author: Thomas Zastrow

    Date: 28 Feb, 2017

    Dear all,
    I took a look at Tobias minimum functions. Mostly, the functions which
    are dealing with the collections or the members metadata are not in my
    implementation so far.
    If someone (;-)) wants to implement these, Reptors collections file
    would need a more sophisticated data structure. I would suggest to use
    Json structures: a header with the key "collection" takes the metadata
    of the collection itself, followed by a list of "members" with the
    metadata for every member. From such a file, all functions mentioned by
    Tobias could be served.
    Please find attached an example - at least, its just c&p some of the
    structures from the Swagger API.
    Best,
    Tom

submit a comment