summary of recent API changes

31 Jul 2017

Hi all
I think we can consider the Collections API swagger spec frozen now.
I've tagged it as Release Candidate 1.0 (rc1.0.0)
As promised, here is a summary of recent changes (these are changes made
since P9):
You can see the details of these in the commit log:
https://github.com/RDACollectionsWG/apidocs/commits/master
Model Changes:
- a "*description*" property was added to the *MemberItem* object
- a "*dateUpdated*" property was added to
the*CollectionItemMappingMetadata *object (to enable specification of
the date a member item was added to a collection)
- a "*dateCreated*" property was added to the *CollectionProperties*
object (to enable specification of the data a collection was created)
Operation Request/Response Changes:
- a "*409*" error response code was added to the */collections* and
*/collections/{id}/members* *POST* requests to report the error
condition in response to an attempt to create a collection or member
item where an item with the supplied ID already exists
- */collections* and */collections/{id}/members* *POST* requests now
each take an array of objects as input rather than an individual object
- the optional "*cursor" *parameter was added to the */collections GET
*request to support pagination
Let me know if there are any questions.
Best
Bridget

  • Thomas Zastrow's picture

    Author: Thomas Zastrow

    Date: 31 Jul, 2017

    Thanks Bridget. I hope that the next weeks I can implement it in Reptor,
    so ḿy homework should be done before the plenary!

  • Tobias Weigel's picture

    Author: Tobias Weigel

    Date: 02 Aug, 2017

    Hi Bridget,
    Ulrich posed a question to me regarding the /collections POST call for
    creating masses of collections and we ended up wondering how this will
    actually work, and whether it will be so extensive that it might pose
    barriers for implementations.
    Is the first call meant to create collections only or will there also be
    collection items put into the new collections within this request? The
    latter would to us imply that the JSON content needs to be some form of
    "array of arrays", which will be quite complex. Secondly, how are the
    multiple sets of properties & capabilities for the multiple new
    collections handled?
    Also, I don't actually see this in the Swagger UI, but the spec reads
    correct to me (accept array type). I assume this is just a shortcoming
    of the UI.
    Best, Tobias
    --
    Dr. Tobias Weigel
    Abteilung Datenmanagement
    Deutsches Klimarechenzentrum GmbH (DKRZ)
    Bundesstraße 45 a • 20146 Hamburg • Germany
    Phone: +49 40 460094-104
    Email: ***@***.***
    URL: http://www.dkrz.de
    ORCID: orcid.org/0000-0002-4040-0215
    Geschäftsführer: Prof. Dr. Thomas Ludwig
    Sitz der Gesellschaft: Hamburg
    Amtsgericht Hamburg HRB 39784

  • Bridget Almas's picture

    Author: Bridget Almas

    Date: 02 Aug, 2017

    Hi Tobias and Ulrich,
    The intent of the collections POST change is to only allow creation of
    multiple collections at once, not creation of collections along with
    with their members. That was never supported up until now, at least not
    explicitly.
    I'll take another look at the spec document to be sure it's reflected
    correctly. It does seem to look a little weird in the UI.
    Thanks!!
    Bridget

  • Tobias Weigel's picture

    Author: Tobias Weigel

    Date: 02 Aug, 2017

    Hi Bridget,
    ok, thanks - that means that what we feared is definitely not possible
    nor intended. I agree that this might not be reflected in the UI, though
    as long as it shows less than is actually possible and not more we are
    somewhat safe. So no big worries - there are no other comments from my
    side on the RC.
    Best, Tobias
    --
    Dr. Tobias Weigel
    Abteilung Datenmanagement
    Deutsches Klimarechenzentrum GmbH (DKRZ)
    Bundesstraße 45 a • 20146 Hamburg • Germany
    Phone: +49 40 460094-104
    Email: ***@***.***
    URL: http://www.dkrz.de
    ORCID: orcid.org/0000-0002-4040-0215
    Geschäftsführer: Prof. Dr. Thomas Ludwig
    Sitz der Gesellschaft: Hamburg
    Amtsgericht Hamburg HRB 39784

  • Frederik Baumgardt's picture

    Author: Frederik Baumgardt

    Date: 02 Aug, 2017

    Hi Tobias and Bridget,
    Yes, the fact that we’re accepting arrays is a bit low-key in the Swagger UI — just a set of square brackets around the CollectionObject. We could add a description in the Implementation Notes, yay or nay?
    Best,
    Frederik

  • Bridget Almas's picture

    Author: Bridget Almas

    Date: 02 Aug, 2017

    Yes I think so, but also the way the model is reflected now in the UI is
    a little wonky. It says it's an array of InlineModel rather than
    CollectionObjects.

  • Ulrich Schwardmann's picture

    Author: Ulrich Schwardmann

    Date: 03 Aug, 2017

    Hi Bridget, all,
    sorry for starting a new discussion about the Collections API spec, I
    hope its not too late, but:
    should we not additionally allow the */collections* *POST* request to
    return the PID (or list of PIDs for an array of objects) of the newly
    created collection(s)?
    Reason: We allow ||"providesCollectionPids" to be true in the features,
    but there is currently no way defined, how the new PID provided by this
    service is communicated back to the client. I currently only see the way
    to provide a known PID for each collection in advance. But this means,
    that the client uses some other service and does not need this feature
    of PID provision in the service. Or did I miss something?
    Consequence of allowing to return the PID(s) would be, that
    "providesCollectionPids" : true and "asynchronousActions" : true would
    not be allowed together, because the first requires synchronisation by a
    list of PIDs as meaningful response. But this could be documented in the
    API spec for the features (s.b.).
    Another consequence would be, that the "id" string in the data field
    would be optional or could be an empty string, which is currently, as
    far as I can see, the case in the API spec anyway. Only by not giving
    any feedback about created PIDs for new collections the "id" string
    implicitely becomes mandatory.
    Such a change would not have any immediate consequences for already
    given implementations, because it is just another option, which makes
    this change less painful.
    My suggestion for the API spec changement would be:
    1)for post /collections Create a new collection, Implementation
    Notes, Response Messages:
    Response Class (Status 201) Successful creation. +++Empty response or
    list of identifiers for created collections, if "providesCollectionPids"
    is true in the features +++
    for get /features Gets the service-level features. Implementation Notes:
    This request returns the service-level features. Examples of
    service-level features might include whether or not the service supports
    assignment of PIDs for collection members, whether it supports
    pagination and cursors, whether it enforces access controls, etc.
    +++ (be aware, that "providesCollectionPids" : true needs
    synchronisation by responding a collection PID list for collection
    creation and would not also allow "asynchronousActions" : true) +++
    What do you think?

  • Bridget Almas's picture

    Author: Bridget Almas

    Date: 03 Aug, 2017

    Hi Ulrich,
    If I'm not mistaken, this is already in place. We had an issue about
    this previously (https://github.com/RDACollectionsWG/apidocs/issues/10)
    and ascertained that the collections POST request returns the
    CollectionObject (incuding the ID, whether it was supplied by the client
    or the service), and it now returns an array of CollectionObjects.
    But I see that the Swagger UI does not show this very clearly. The spec has:
    "responses": {
    "201": {
    "description": "Successful creation",
    "schema": {
    "type": "array",
    "items": {
    "$ref": "#/definitions/CollectionObject"
    }
    }
    },
    "202": {
    "description": "Accepted create request. Empty response
    body. (For asyncrhonous requests, if supported by the service features)."
    },
    But it doesn't show up so cleanly in the UI, because of the way it puts
    the default success response, i.e the 201, as a Response Class and
    doesn't include in the list of alternative Response Messages below.
    I'll enter an issue to update the description of the request to make it
    clearer. Will that address your concern?
    We also have an open issue about the response type on asynchronous
    requests (See https://github.com/RDACollectionsWG/apidocs/issues/14) but
    I think that will be deferred to the future.
    Thanks!

  • Ulrich Schwardmann's picture

    Author: Ulrich Schwardmann

    Date: 03 Aug, 2017

    Thanks Bridget,
    yes, that fully addresses my concern.
    --
    Mit freundlichem Gruss
    Ulrich Schwardmann
    Phone:+49-551-201-1542 Email:***@***.*** _____ _____ ___
    Gesellschaft fuer wissenschaftliche / __\ \ / / \ / __|
    Datenverarbeitung mbH Goettingen (GWDG) | (_--\ \/\/ /| |) | (_--
    Am Fassberg 11 D-37077 Goettingen Germany \___| \_/\_/ |___/ \___|
    URL: http://www.gwdg.de E-Mail: ***@***.***
    Tel.: +49 (0)551 201-1510 Fax: +49 (0)551 201-2150
    Geschaeftsfuehrer: Prof. Dr. Ramin Yahyapour
    Aufsichtsratsvorsitzender: Prof. Dr. Norbert Lossau
    Sitz der Gesellschaft: Goettingen Registergericht: Goettingen
    Handelsregister-Nr. B 598 Zertifiziert nach ISO 9001

submit a comment

summary of recent API changes | RDA

Error

The website encountered an unexpected error. Please try again later.