[Bridget Almas]

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

Discussion

[Thomas Zastrow]

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]

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]

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]

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]

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]

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]

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]

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]

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

[Author]

Replies