API Feedback

25 Oct 2016

Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
> ok
* POST /collections/{id}/members:

o Do we need support for adding multiple items at once? (would be
convenient, but perhaps also efficient on database)
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
> ok
* POST /collections/{id}/members:

o Do we need support for adding multiple items at once? (would be
convenient, but perhaps also efficient on database)
> I'm happy to change this to always accept a list
* PUT /collections/{id}/members/{mid}:

o The content parameter is broken, it currently contains
properties for whole collections.
> Will fix
o If the collection is sorted and the same item appears multiple
times, how does one add it? The {mid} is the item's identifier,
therefore only unique in this context if an index is provided as
well. Do we simply solve this by making the index property
within the "content" parameter structure mandatory?
> This is what we discussed during the call right? I think we may
want a capability which says that new items are added at the end in
a sorted collection?
* GET /collections/{id}/members/{mid}/properties/{property}:

o Shouldn't there be a simple string return value?
> Yes will fix.
Best
Bridget
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
> ok
* POST /collections/{id}/members:

o Do we need support for adding multiple items at once? (would be
convenient, but perhaps also efficient on database)
> I'm happy to change this to always accept a list
* PUT /collections/{id}/members/{mid}:

o The content parameter is broken, it currently contains
properties for whole collections.
> Will fix
o If the collection is sorted and the same item appears multiple
times, how does one add it? The {mid} is the item's identifier,
therefore only unique in this context if an index is provided as
well. Do we simply solve this by making the index property
within the "content" parameter structure mandatory?
> This is what we discussed during the call right? I think we may
want a capability which says that new items are added at the end in
a sorted collection?
* GET /collections/{id}/members/{mid}/properties/{property}:

o Shouldn't there be a simple string return value?
> Yes will fix.
Best
Bridget
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
> ok
* POST /collections/{id}/members:

o Do we need support for adding multiple items at once? (would be
convenient, but perhaps also efficient on database)
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
> ok
* POST /collections/{id}/members:

o Do we need support for adding multiple items at once? (would be
convenient, but perhaps also efficient on database)
> I'm happy to change this to always accept a list
* PUT /collections/{id}/members/{mid}:

o The content parameter is broken, it currently contains
properties for whole collections.
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
> ok
* POST /collections/{id}/members:

o Do we need support for adding multiple items at once? (would be
convenient, but perhaps also efficient on database)
> I'm happy to change this to always accept a list
* PUT /collections/{id}/members/{mid}:

o The content parameter is broken, it currently contains
properties for whole collections.
> Will fix
o If the collection is sorted and the same item appears multiple
times, how does one add it? The {mid} is the item's identifier,
therefore only unique in this context if an index is provided as
well. Do we simply solve this by making the index property
within the "content" parameter structure mandatory?
> This is what we discussed during the call right? I think we may
want a capability which says that new items are added at the end in
a sorted collection?
* GET /collections/{id}/members/{mid}/properties/{property}:

o Shouldn't there be a simple string return value?
> Yes will fix.
Best
Bridget
Tobias,
Thanks for your detailed feedback on the API. I'm responding on list in
case others want to chime in.
* Capabilities/Features:
o All capability entries should be mandatory, so not to leave
ambiguities.
> Agreed
o pidProviderType: What would be example URIs? Are we talking Type
Registry here? Wouldn't a CV be better (but: who will manage that?)?
> When we originally discussed this we talked about using the Type
Registry yes. A controlled vocabulary could be just as good, or we
could just state for now that we support a list of values (RDAPIT,
Handle, ...?)
o (a)synchronous actions - good idea! Does this actually have an
influence on the method design? I currently feel that it does
not, except perhaps for return values or errors.
> I think the main impact is in the response types on the
operations. E.g. the latest version of the spec distinguishes
between 200 and 202 for a number of operations (mainly PUT and
DELETE) depending upon this capability. I see that isn't showing up
everywhere I thought I had defined it though. You can see it on
DELETE /collections/{id}/members/{mid}
* GET /collections, GET /collections/{id}:

o How exactly does pagination with cursors work? I am missing a
method/parameter for this. Or is a cursor perhaps a temporary
method URL?
> I was basing this on the Twitter approach to cursors. The
CollectionResultset contains 2 optional attributes: next_cursor and
prev_cursor. These are meant to contain tokens that can be used to
get the next and previous page in a resultset. You would then
supply one of these in a repeat call to the same GET request that
produced them. E.g.
GET /collections
GET /collections?cursor=1234jasdlkja
*
o maxDepth: I think traversal in "up" direction should be a
separate parameter; it may be much easier (less items) than
"down" traversal, but it may also be impossible, depending on
implementation.
> so you prefer a separate parameter to a negative number semantic,
which I think is what we discussed previously?
o Collection capabilities should be mandatory..?
> yes they are, the UI just isn't showing that very well
o Collection ownership: Clear for citation/library use cases, but
not so clear for DO Cloud.
> do you have suggestions for what we should do for that?
o sort criteria: stub. Not too important, do later.
> Agreed
* POST /collections:

o id: may also be optional; an implementation may provide
auto-generated identifiers; this should be visible in the
service capabilities
> Agreed
o capabilities: should be mandatory; alternatively, clearly state
default values (unordered, immutable).
> Agreed
o maxDepth: Is this really a part of a collection's capabilities
or is it rather computed by the service on the fly?
> I'm not sure. It does feel a bit more like a service feature than
a collection capability.
* GET /collections/{id}/ops/matchingMembers:

o parameter memberProperties: all criteria should be optional.
> hmm. yes this is going to be tricky to represent in the swagger
spec I think. I'll look into it.
o perhaps error code 412 (precondition failed) for clash in role
support/ordering.
> ok
* POST /collections/{id}/members:

o Do we need support for adding multiple items at once? (would be
convenient, but perhaps also efficient on database)
> I'm happy to change this to always accept a list
* PUT /collections/{id}/members/{mid}:

o The content parameter is broken, it currently contains
properties for whole collections.
> Will fix
o If the collection is sorted and the same item appears multiple
times, how does one add it? The {mid} is the item's identifier,
therefore only unique in this context if an index is provided as
well. Do we simply solve this by making the index property
within the "content" parameter structure mandatory?
> This is what we discussed during the call right? I think we may
want a capability which says that new items are added at the end in
a sorted collection?
* GET /collections/{id}/members/{mid}/properties/{property}:

o Shouldn't there be a simple string return value?
Best
Bridget

  • Tobias Weigel's picture

    Author: Tobias Weigel

    Date: 27 Oct, 2016

    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    >
    > o pidProviderType: What would be example URIs? Are we talking Type
    > Registry here? Wouldn't a CV be better (but: who will manage that?)?
    >
    > > When we originally discussed this we talked about using the Type
    > Registry yes. A controlled vocabulary could be just as good, or we
    > could just state for now that we support a list of values (RDAPIT,
    > Handle, ...?)
    I'm not sure whether PIT is the right way to go here. It's really more a
    registry kind of question than a PID record one. Even for the DTR it's a
    conceptual stretch. So maybe the spec could say, for now: Result should
    be either an entry from a CV, maintained by the service end-point with
    'unambigous' PID service names, or a registered data type indicating a
    PID service.
    It's not a very satisfying solution, but for now it might be enough.
    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    >
    > o pidProviderType: What would be example URIs? Are we talking Type
    > Registry here? Wouldn't a CV be better (but: who will manage that?)?
    >
    > > When we originally discussed this we talked about using the Type
    > Registry yes. A controlled vocabulary could be just as good, or we
    > could just state for now that we support a list of values (RDAPIT,
    > Handle, ...?)
    I'm not sure whether PIT is the right way to go here. It's really more a
    registry kind of question than a PID record one. Even for the DTR it's a
    conceptual stretch. So maybe the spec could say, for now: Result should
    be either an entry from a CV, maintained by the service end-point with
    'unambigous' PID service names, or a registered data type indicating a
    PID service.
    It's not a very satisfying solution, but for now it might be enough.
    >
    > o (a)synchronous actions - good idea! Does this actually have an
    > influence on the method design? I currently feel that it does
    > not, except perhaps for return values or errors.
    >
    > > I think the main impact is in the response types on the
    > operations. E.g. the latest version of the spec distinguishes
    > between 200 and 202 for a number of operations (mainly PUT and
    > DELETE) depending upon this capability. I see that isn't showing up
    > everywhere I thought I had defined it though. You can see it on
    > DELETE /collections/{id}/members/{mid}
    Yes, the 200/202 distinction sounds absolutely right. I can see it now
    on the various DELETEs; the POSTs are only listing error responses.
    Anyway, I don't think it is totally urgent to clear those things up now
    - I think the principle is agreed. I don't see any other points that
    might be affected by asynchronous mode.
    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    >
    > o pidProviderType: What would be example URIs? Are we talking Type
    > Registry here? Wouldn't a CV be better (but: who will manage that?)?
    >
    > > When we originally discussed this we talked about using the Type
    > Registry yes. A controlled vocabulary could be just as good, or we
    > could just state for now that we support a list of values (RDAPIT,
    > Handle, ...?)
    I'm not sure whether PIT is the right way to go here. It's really more a
    registry kind of question than a PID record one. Even for the DTR it's a
    conceptual stretch. So maybe the spec could say, for now: Result should
    be either an entry from a CV, maintained by the service end-point with
    'unambigous' PID service names, or a registered data type indicating a
    PID service.
    It's not a very satisfying solution, but for now it might be enough.
    >
    > o (a)synchronous actions - good idea! Does this actually have an
    > influence on the method design? I currently feel that it does
    > not, except perhaps for return values or errors.
    >
    > > I think the main impact is in the response types on the
    > operations. E.g. the latest version of the spec distinguishes
    > between 200 and 202 for a number of operations (mainly PUT and
    > DELETE) depending upon this capability. I see that isn't showing up
    > everywhere I thought I had defined it though. You can see it on
    > DELETE /collections/{id}/members/{mid}
    Yes, the 200/202 distinction sounds absolutely right. I can see it now
    on the various DELETEs; the POSTs are only listing error responses.
    Anyway, I don't think it is totally urgent to clear those things up now
    - I think the principle is agreed. I don't see any other points that
    might be affected by asynchronous mode.
    >
    >
    > * GET /collections, GET /collections/{id}:
    >
    >
    > o How exactly does pagination with cursors work? I am missing a
    > method/parameter for this. Or is a cursor perhaps a temporary
    > method URL?
    >
    > > I was basing this on the Twitter approach to cursors. The
    > CollectionResultset contains 2 optional attributes: next_cursor and
    > prev_cursor. These are meant to contain tokens that can be used to
    > get the next and previous page in a resultset. You would then
    > supply one of these in a repeat call to the same GET request that
    > produced them. E.g.
    >
    > GET /collections
    > GET /collections?cursor=1234jasdlkja
    OK. I'm wondering what this will mean for implementations. You'd
    probably keep your database cursors in a cache and evict them after a
    stale period with no action. Do we want to specify the time-out for
    this? E.g. 5 minutes?
    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    >
    > o pidProviderType: What would be example URIs? Are we talking Type
    > Registry here? Wouldn't a CV be better (but: who will manage that?)?
    >
    > > When we originally discussed this we talked about using the Type
    > Registry yes. A controlled vocabulary could be just as good, or we
    > could just state for now that we support a list of values (RDAPIT,
    > Handle, ...?)
    I'm not sure whether PIT is the right way to go here. It's really more a
    registry kind of question than a PID record one. Even for the DTR it's a
    conceptual stretch. So maybe the spec could say, for now: Result should
    be either an entry from a CV, maintained by the service end-point with
    'unambigous' PID service names, or a registered data type indicating a
    PID service.
    It's not a very satisfying solution, but for now it might be enough.
    >
    > o (a)synchronous actions - good idea! Does this actually have an
    > influence on the method design? I currently feel that it does
    > not, except perhaps for return values or errors.
    >
    > > I think the main impact is in the response types on the
    > operations. E.g. the latest version of the spec distinguishes
    > between 200 and 202 for a number of operations (mainly PUT and
    > DELETE) depending upon this capability. I see that isn't showing up
    > everywhere I thought I had defined it though. You can see it on
    > DELETE /collections/{id}/members/{mid}
    Yes, the 200/202 distinction sounds absolutely right. I can see it now
    on the various DELETEs; the POSTs are only listing error responses.
    Anyway, I don't think it is totally urgent to clear those things up now
    - I think the principle is agreed. I don't see any other points that
    might be affected by asynchronous mode.
    >
    >
    > * GET /collections, GET /collections/{id}:
    >
    >
    > o How exactly does pagination with cursors work? I am missing a
    > method/parameter for this. Or is a cursor perhaps a temporary
    > method URL?
    >
    > > I was basing this on the Twitter approach to cursors. The
    > CollectionResultset contains 2 optional attributes: next_cursor and
    > prev_cursor. These are meant to contain tokens that can be used to
    > get the next and previous page in a resultset. You would then
    > supply one of these in a repeat call to the same GET request that
    > produced them. E.g.
    >
    > GET /collections
    > GET /collections?cursor=1234jasdlkja
    OK. I'm wondering what this will mean for implementations. You'd
    probably keep your database cursors in a cache and evict them after a
    stale period with no action. Do we want to specify the time-out for
    this? E.g. 5 minutes?
    >
    > *
    > o maxDepth: I think traversal in "up" direction should be a
    > separate parameter; it may be much easier (less items) than
    > "down" traversal, but it may also be impossible, depending on
    > implementation.
    >
    > > so you prefer a separate parameter to a negative number semantic,
    > which I think is what we discussed previously?
    Ah, I think I'm mixing up two issues here. The original point I
    addressed was the question whether/how to indicate traversal up. But the
    down semantics are also open.
    Suggestion:
    A GET return value maxDepth = -1 means "you can query infinite depth
    down". You are still right, I'd prefer that to a separate attribute.
    The collection GET methods would also need a query param for maxDepth.
    That will allow you to retrieve a hierarchy with one call. But this
    should be also optional, so a new int switch in the service features
    "supportedDepthTraversal".
    The whole thing about traversing up needs more thought.
    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    >
    > o pidProviderType: What would be example URIs? Are we talking Type
    > Registry here? Wouldn't a CV be better (but: who will manage that?)?
    >
    > > When we originally discussed this we talked about using the Type
    > Registry yes. A controlled vocabulary could be just as good, or we
    > could just state for now that we support a list of values (RDAPIT,
    > Handle, ...?)
    I'm not sure whether PIT is the right way to go here. It's really more a
    registry kind of question than a PID record one. Even for the DTR it's a
    conceptual stretch. So maybe the spec could say, for now: Result should
    be either an entry from a CV, maintained by the service end-point with
    'unambigous' PID service names, or a registered data type indicating a
    PID service.
    It's not a very satisfying solution, but for now it might be enough.
    >
    > o (a)synchronous actions - good idea! Does this actually have an
    > influence on the method design? I currently feel that it does
    > not, except perhaps for return values or errors.
    >
    > > I think the main impact is in the response types on the
    > operations. E.g. the latest version of the spec distinguishes
    > between 200 and 202 for a number of operations (mainly PUT and
    > DELETE) depending upon this capability. I see that isn't showing up
    > everywhere I thought I had defined it though. You can see it on
    > DELETE /collections/{id}/members/{mid}
    Yes, the 200/202 distinction sounds absolutely right. I can see it now
    on the various DELETEs; the POSTs are only listing error responses.
    Anyway, I don't think it is totally urgent to clear those things up now
    - I think the principle is agreed. I don't see any other points that
    might be affected by asynchronous mode.
    >
    >
    > * GET /collections, GET /collections/{id}:
    >
    >
    > o How exactly does pagination with cursors work? I am missing a
    > method/parameter for this. Or is a cursor perhaps a temporary
    > method URL?
    >
    > > I was basing this on the Twitter approach to cursors. The
    > CollectionResultset contains 2 optional attributes: next_cursor and
    > prev_cursor. These are meant to contain tokens that can be used to
    > get the next and previous page in a resultset. You would then
    > supply one of these in a repeat call to the same GET request that
    > produced them. E.g.
    >
    > GET /collections
    > GET /collections?cursor=1234jasdlkja
    OK. I'm wondering what this will mean for implementations. You'd
    probably keep your database cursors in a cache and evict them after a
    stale period with no action. Do we want to specify the time-out for
    this? E.g. 5 minutes?
    >
    > *
    > o maxDepth: I think traversal in "up" direction should be a
    > separate parameter; it may be much easier (less items) than
    > "down" traversal, but it may also be impossible, depending on
    > implementation.
    >
    > > so you prefer a separate parameter to a negative number semantic,
    > which I think is what we discussed previously?
    Ah, I think I'm mixing up two issues here. The original point I
    addressed was the question whether/how to indicate traversal up. But the
    down semantics are also open.
    Suggestion:
    A GET return value maxDepth = -1 means "you can query infinite depth
    down". You are still right, I'd prefer that to a separate attribute.
    The collection GET methods would also need a query param for maxDepth.
    That will allow you to retrieve a hierarchy with one call. But this
    should be also optional, so a new int switch in the service features
    "supportedDepthTraversal".
    The whole thing about traversing up needs more thought.
    >
    > o Collection ownership: Clear for citation/library use cases, but
    > not so clear for DO Cloud.
    >
    > > do you have suggestions for what we should do for that?
    I was thinking whether we will always have an owner in a DO cloud
    solution (where we are often not dealing with properly annotated,
    archived data). In that case, an owner might be too much to ask. On the
    other hand, putting it in the API is also a statement where we might
    actually encourage a better practice. So maybe that is an argument
    against making it optional - leaving it as it is right now. I don't
    think we can move beyond a string type here, as well. In citation use
    cases, ORCIDs would be great, but that's not the same for others.
    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    >
    > o pidProviderType: What would be example URIs? Are we talking Type
    > Registry here? Wouldn't a CV be better (but: who will manage that?)?
    >
    > > When we originally discussed this we talked about using the Type
    > Registry yes. A controlled vocabulary could be just as good, or we
    > could just state for now that we support a list of values (RDAPIT,
    > Handle, ...?)
    I'm not sure whether PIT is the right way to go here. It's really more a
    registry kind of question than a PID record one. Even for the DTR it's a
    conceptual stretch. So maybe the spec could say, for now: Result should
    be either an entry from a CV, maintained by the service end-point with
    'unambigous' PID service names, or a registered data type indicating a
    PID service.
    It's not a very satisfying solution, but for now it might be enough.
    >
    > o (a)synchronous actions - good idea! Does this actually have an
    > influence on the method design? I currently feel that it does
    > not, except perhaps for return values or errors.
    >
    > > I think the main impact is in the response types on the
    > operations. E.g. the latest version of the spec distinguishes
    > between 200 and 202 for a number of operations (mainly PUT and
    > DELETE) depending upon this capability. I see that isn't showing up
    > everywhere I thought I had defined it though. You can see it on
    > DELETE /collections/{id}/members/{mid}
    Yes, the 200/202 distinction sounds absolutely right. I can see it now
    on the various DELETEs; the POSTs are only listing error responses.
    Anyway, I don't think it is totally urgent to clear those things up now
    - I think the principle is agreed. I don't see any other points that
    might be affected by asynchronous mode.
    >
    >
    > * GET /collections, GET /collections/{id}:
    >
    >
    > o How exactly does pagination with cursors work? I am missing a
    > method/parameter for this. Or is a cursor perhaps a temporary
    > method URL?
    >
    > > I was basing this on the Twitter approach to cursors. The
    > CollectionResultset contains 2 optional attributes: next_cursor and
    > prev_cursor. These are meant to contain tokens that can be used to
    > get the next and previous page in a resultset. You would then
    > supply one of these in a repeat call to the same GET request that
    > produced them. E.g.
    >
    > GET /collections
    > GET /collections?cursor=1234jasdlkja
    OK. I'm wondering what this will mean for implementations. You'd
    probably keep your database cursors in a cache and evict them after a
    stale period with no action. Do we want to specify the time-out for
    this? E.g. 5 minutes?
    >
    > *
    > o maxDepth: I think traversal in "up" direction should be a
    > separate parameter; it may be much easier (less items) than
    > "down" traversal, but it may also be impossible, depending on
    > implementation.
    >
    > > so you prefer a separate parameter to a negative number semantic,
    > which I think is what we discussed previously?
    Ah, I think I'm mixing up two issues here. The original point I
    addressed was the question whether/how to indicate traversal up. But the
    down semantics are also open.
    Suggestion:
    A GET return value maxDepth = -1 means "you can query infinite depth
    down". You are still right, I'd prefer that to a separate attribute.
    The collection GET methods would also need a query param for maxDepth.
    That will allow you to retrieve a hierarchy with one call. But this
    should be also optional, so a new int switch in the service features
    "supportedDepthTraversal".
    The whole thing about traversing up needs more thought.
    >
    > o Collection ownership: Clear for citation/library use cases, but
    > not so clear for DO Cloud.
    >
    > > do you have suggestions for what we should do for that?
    I was thinking whether we will always have an owner in a DO cloud
    solution (where we are often not dealing with properly annotated,
    archived data). In that case, an owner might be too much to ask. On the
    other hand, putting it in the API is also a statement where we might
    actually encourage a better practice. So maybe that is an argument
    against making it optional - leaving it as it is right now. I don't
    think we can move beyond a string type here, as well. In citation use
    cases, ORCIDs would be great, but that's not the same for others.
    >
    > o maxDepth: Is this really a part of a collection's capabilities
    > or is it rather computed by the service on the fly?
    >
    > > I'm not sure. It does feel a bit more like a service feature than
    > a collection capability.
    I concur. So at least for now, we can put it in the features.
    Hi Bridget,
    thank you for the detailed response. I'm answering to your comments inline.
    Btw, what do you actually use for editing the spec? The official swagger
    editor?
    >
    > o pidProviderType: What would be example URIs? Are we talking Type
    > Registry here? Wouldn't a CV be better (but: who will manage that?)?
    >
    > > When we originally discussed this we talked about using the Type
    > Registry yes. A controlled vocabulary could be just as good, or we
    > could just state for now that we support a list of values (RDAPIT,
    > Handle, ...?)
    I'm not sure whether PIT is the right way to go here. It's really more a
    registry kind of question than a PID record one. Even for the DTR it's a
    conceptual stretch. So maybe the spec could say, for now: Result should
    be either an entry from a CV, maintained by the service end-point with
    'unambigous' PID service names, or a registered data type indicating a
    PID service.
    It's not a very satisfying solution, but for now it might be enough.
    >
    > o (a)synchronous actions - good idea! Does this actually have an
    > influence on the method design? I currently feel that it does
    > not, except perhaps for return values or errors.
    >
    > > I think the main impact is in the response types on the
    > operations. E.g. the latest version of the spec distinguishes
    > between 200 and 202 for a number of operations (mainly PUT and
    > DELETE) depending upon this capability. I see that isn't showing up
    > everywhere I thought I had defined it though. You can see it on
    > DELETE /collections/{id}/members/{mid}
    Yes, the 200/202 distinction sounds absolutely right. I can see it now
    on the various DELETEs; the POSTs are only listing error responses.
    Anyway, I don't think it is totally urgent to clear those things up now
    - I think the principle is agreed. I don't see any other points that
    might be affected by asynchronous mode.
    >
    >
    > * GET /collections, GET /collections/{id}:
    >
    >
    > o How exactly does pagination with cursors work? I am missing a
    > method/parameter for this. Or is a cursor perhaps a temporary
    > method URL?
    >
    > > I was basing this on the Twitter approach to cursors. The
    > CollectionResultset contains 2 optional attributes: next_cursor and
    > prev_cursor. These are meant to contain tokens that can be used to
    > get the next and previous page in a resultset. You would then
    > supply one of these in a repeat call to the same GET request that
    > produced them. E.g.
    >
    > GET /collections
    > GET /collections?cursor=1234jasdlkja
    OK. I'm wondering what this will mean for implementations. You'd
    probably keep your database cursors in a cache and evict them after a
    stale period with no action. Do we want to specify the time-out for
    this? E.g. 5 minutes?
    >
    > *
    > o maxDepth: I think traversal in "up" direction should be a
    > separate parameter; it may be much easier (less items) than
    > "down" traversal, but it may also be impossible, depending on
    > implementation.
    >
    > > so you prefer a separate parameter to a negative number semantic,
    > which I think is what we discussed previously?
    Ah, I think I'm mixing up two issues here. The original point I
    addressed was the question whether/how to indicate traversal up. But the
    down semantics are also open.
    Suggestion:
    A GET return value maxDepth = -1 means "you can query infinite depth
    down". You are still right, I'd prefer that to a separate attribute.
    The collection GET methods would also need a query param for maxDepth.
    That will allow you to retrieve a hierarchy with one call. But this
    should be also optional, so a new int switch in the service features
    "supportedDepthTraversal".
    The whole thing about traversing up needs more thought.
    >
    > o Collection ownership: Clear for citation/library use cases, but
    > not so clear for DO Cloud.
    >
    > > do you have suggestions for what we should do for that?
    I was thinking whether we will always have an owner in a DO cloud
    solution (where we are often not dealing with properly annotated,
    archived data). In that case, an owner might be too much to ask. On the
    other hand, putting it in the API is also a statement where we might
    actually encourage a better practice. So maybe that is an argument
    against making it optional - leaving it as it is right now. I don't
    think we can move beyond a string type here, as well. In citation use
    cases, ORCIDs would be great, but that's not the same for others.
    >
    > o maxDepth: Is this really a part of a collection's capabilities
    > or is it rather computed by the service on the fly?
    >
    > > I'm not sure. It does feel a bit more like a service feature than
    > a collection capability.
    I concur. So at least for now, we can put it in the features.
    > o If the collection is sorted and the same item appears multiple
    > times, how does one add it? The {mid} is the item's identifier,
    > therefore only unique in this context if an index is provided as
    > well. Do we simply solve this by making the index property
    > within the "content" parameter structure mandatory?
    >
    > > This is what we discussed during the call right? I think we may
    > want a capability which says that new items are added at the end in
    > a sorted collection?
    Yes, sorry, I missed that when cleaning up my notes after our
    discussion. And I agree, the "append at the end" mode should be a
    collection capability.
    These mails remain being longer than I want; but there's no way around
    getting some of these details looked at with our collective minds and
    some thinking time.
    Best, Tobias

  • Thomas Zastrow's picture

    Author: Thomas Zastrow

    Date: 27 Oct, 2016

    If necessary, we can provide a server to run the API "in reality" :-)
    --
    Dr. Thomas Zastrow
    Rechenzentrum Garching (RZG) der Max-Planck-Gesellschaft / MPI für Plasmaphysik
    Boltzmannstrasse 2, D-85748 Garching
    Tel +49-89-3299-1457
    http://www.rzg.mpg.de

  • Tobias Weigel's picture

    Author: Tobias Weigel

    Date: 28 Oct, 2016

    Hi Tom,
    thank you, I think that will be one of the next steps - setting up redis
    and then the demo via wsgi.
    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 Nov, 2016

    Hi Tobias
    Sorry for the delay in responding to this. A few more thoughts inline
    below. Will try to have an update to the API with all of the pending
    feedback by the end of next week.
    Best
    Bridget
    Hi Tobias
    Sorry for the delay in responding to this. A few more thoughts inline
    below. Will try to have an update to the API with all of the pending
    feedback by the end of next week.
    Best
    Bridget
    On 10/27/2016 06:05 AM, TobiasWeigel wrote:
    > Hi Bridget,
    >
    > thank you for the detailed response. I'm answering to your comments
    > inline.
    > Btw, what do you actually use for editing the spec? The official
    > swagger editor?
    >
    >>
    >> o pidProviderType: What would be example URIs? Are we talking Type
    >> Registry here? Wouldn't a CV be better (but: who will manage
    >> that?)?
    >>
    >> > When we originally discussed this we talked about using the Type
    >> Registry yes. A controlled vocabulary could be just as good, or we
    >> could just state for now that we support a list of values (RDAPIT,
    >> Handle, ...?)
    >
    > I'm not sure whether PIT is the right way to go here. It's really more
    > a registry kind of question than a PID record one. Even for the DTR
    > it's a conceptual stretch. So maybe the spec could say, for now:
    > Result should be either an entry from a CV, maintained by the service
    > end-point with 'unambigous' PID service names, or a registered data
    > type indicating a PID service.
    > It's not a very satisfying solution, but for now it might be enough.
    > Agreed.
    >
    >>
    >> o (a)synchronous actions - good idea! Does this actually have an
    >> influence on the method design? I currently feel that it does
    >> not, except perhaps for return values or errors.
    >>
    >> > I think the main impact is in the response types on the
    >> operations. E.g. the latest version of the spec distinguishes
    >> between 200 and 202 for a number of operations (mainly PUT and
    >> DELETE) depending upon this capability. I see that isn't showing up
    >> everywhere I thought I had defined it though. You can see it on
    >> DELETE /collections/{id}/members/{mid}
    >
    > Yes, the 200/202 distinction sounds absolutely right. I can see it now
    > on the various DELETEs; the POSTs are only listing error responses.
    > Anyway, I don't think it is totally urgent to clear those things up
    > now - I think the principle is agreed. I don't see any other points
    > that might be affected by asynchronous mode.
    >
    >>
    >>
    >> * GET /collections, GET /collections/{id}:
    >>
    >>
    >> o How exactly does pagination with cursors work? I am missing a
    >> method/parameter for this. Or is a cursor perhaps a temporary
    >> method URL?
    >>
    >> > I was basing this on the Twitter approach to cursors. The
    >> CollectionResultset contains 2 optional attributes: next_cursor and
    >> prev_cursor. These are meant to contain tokens that can be used to
    >> get the next and previous page in a resultset. You would then
    >> supply one of these in a repeat call to the same GET request that
    >> produced them. E.g.
    >>
    >> GET /collections
    >> GET /collections?cursor=1234jasdlkja
    >
    > OK. I'm wondering what this will mean for implementations. You'd
    > probably keep your database cursors in a cache and evict them after a
    > stale period with no action. Do we want to specify the time-out for
    > this? E.g. 5 minutes?
    > I'll investigate a bit to see if I can find some API best practices
    Hi Tobias
    Sorry for the delay in responding to this. A few more thoughts inline
    below. Will try to have an update to the API with all of the pending
    feedback by the end of next week.
    Best
    Bridget
    On 10/27/2016 06:05 AM, TobiasWeigel wrote:
    > Hi Bridget,
    >
    > thank you for the detailed response. I'm answering to your comments
    > inline.
    > Btw, what do you actually use for editing the spec? The official
    > swagger editor?
    >
    >>
    >> o pidProviderType: What would be example URIs? Are we talking Type
    >> Registry here? Wouldn't a CV be better (but: who will manage
    >> that?)?
    >>
    >> > When we originally discussed this we talked about using the Type
    >> Registry yes. A controlled vocabulary could be just as good, or we
    >> could just state for now that we support a list of values (RDAPIT,
    >> Handle, ...?)
    >
    > I'm not sure whether PIT is the right way to go here. It's really more
    > a registry kind of question than a PID record one. Even for the DTR
    > it's a conceptual stretch. So maybe the spec could say, for now:
    > Result should be either an entry from a CV, maintained by the service
    > end-point with 'unambigous' PID service names, or a registered data
    > type indicating a PID service.
    > It's not a very satisfying solution, but for now it might be enough.
    > Agreed.
    >
    >>
    >> o (a)synchronous actions - good idea! Does this actually have an
    >> influence on the method design? I currently feel that it does
    >> not, except perhaps for return values or errors.
    >>
    >> > I think the main impact is in the response types on the
    >> operations. E.g. the latest version of the spec distinguishes
    >> between 200 and 202 for a number of operations (mainly PUT and
    >> DELETE) depending upon this capability. I see that isn't showing up
    >> everywhere I thought I had defined it though. You can see it on
    >> DELETE /collections/{id}/members/{mid}
    >
    > Yes, the 200/202 distinction sounds absolutely right. I can see it now
    > on the various DELETEs; the POSTs are only listing error responses.
    > Anyway, I don't think it is totally urgent to clear those things up
    > now - I think the principle is agreed. I don't see any other points
    > that might be affected by asynchronous mode.
    >
    >>
    >>
    >> * GET /collections, GET /collections/{id}:
    >>
    >>
    >> o How exactly does pagination with cursors work? I am missing a
    >> method/parameter for this. Or is a cursor perhaps a temporary
    >> method URL?
    >>
    >> > I was basing this on the Twitter approach to cursors. The
    >> CollectionResultset contains 2 optional attributes: next_cursor and
    >> prev_cursor. These are meant to contain tokens that can be used to
    >> get the next and previous page in a resultset. You would then
    >> supply one of these in a repeat call to the same GET request that
    >> produced them. E.g.
    >>
    >> GET /collections
    >> GET /collections?cursor=1234jasdlkja
    >
    > OK. I'm wondering what this will mean for implementations. You'd
    > probably keep your database cursors in a cache and evict them after a
    > stale period with no action. Do we want to specify the time-out for
    > this? E.g. 5 minutes?
    > I'll investigate a bit to see if I can find some API best practices
    around timeouts and cursors.
    >
    >>
    >> *
    >> o maxDepth: I think traversal in "up" direction should be a
    >> separate parameter; it may be much easier (less items) than
    >> "down" traversal, but it may also be impossible, depending on
    >> implementation.
    >>
    >> > so you prefer a separate parameter to a negative number semantic,
    >> which I think is what we discussed previously?
    >
    > Ah, I think I'm mixing up two issues here. The original point I
    > addressed was the question whether/how to indicate traversal up. But
    > the down semantics are also open.
    >
    > Suggestion:
    > A GET return value maxDepth = -1 means "you can query infinite depth
    > down". You are still right, I'd prefer that to a separate attribute.
    > The collection GET methods would also need a query param for maxDepth.
    > That will allow you to retrieve a hierarchy with one call. But this
    > should be also optional, so a new int switch in the service features
    > "supportedDepthTraversal".
    >
    > The whole thing about traversing up needs more thought.
    > Agreed on all points.
    >
    >>
    >> o Collection ownership: Clear for citation/library use cases, but
    >> not so clear for DO Cloud.
    >>
    >> > do you have suggestions for what we should do for that?
    >
    > I was thinking whether we will always have an owner in a DO cloud
    > solution (where we are often not dealing with properly annotated,
    > archived data). In that case, an owner might be too much to ask. On
    > the other hand, putting it in the API is also a statement where we
    > might actually encourage a better practice. So maybe that is an
    > argument against making it optional - leaving it as it is right now. I
    > don't think we can move beyond a string type here, as well. In
    > citation use cases, ORCIDs would be great, but that's not the same for
    > others.
    > I guess there is nothing to prevent use of "unknown" as the value

submit a comment