A few comments about the spec at facilityregistry.org

Legacy facility-registry
1

Hi guys

In preparation for the call today, I have quickly gone through the spec at facilityregistry.org and have some comments, some are just simple mistakes that needs to be fixed, and others could be points for disussion…

  1. It says 1.0 on http://facilityregistry.org/ already, maybe it should say DRAFT?

  2. HTTP Status Codes: I don’t like that we are specifying what the codes mean, but if we do

    lets at least update them so that they are correct with regards to responses, e.g.

    201 Created should return the body.

    (I really don’t like that it in the spec)

  3. Success: Again we are saying that it return 200 OK for success?

  4. Authentication: Please stop saying ‘token’

  5. Authentication: Please just point to where basic auth is defined, don’t give a step-by-step

    instruction on how to do it.

  6. Versioning: We are linking to http://semver.org, but which version are we targetting? there are

    multiple versions. If we are linking to a page describing it, do we need to also describe it ourselves?

  7. Facility Object: single quotes are not legal JSON!

  8. Extended Properties: I’m very confused what we should do about merging here. Should we also store

    potentially stale data from other providers? I assume not?

  9. Identifier Properties: Same here. Are we suppose to merge this data? if new identifiers are included in

    stream? or do we only care about those that are important to us? If registry A added the identifier, is

    registry B allowed to change it?

  10. SORTING: Is /facilities.json?sortAsc=properties.MySuperProperty allowed here? or only core props?

  11. PAGINATION: I think ?limit=off looks horrible. We are giving another meaning to the limit field, does

    this mean paging is off? what about offset? is ?limit=off&offset=10 allowed? if we want to re-use the

    limit field, maybe limit=0 would be better?

  12. FILTERING FACILITIES: I assume people have agreed on this format? it doesn’t look very nice.

  13. FILTER BY ACTIVE STATUS: why is this needed? isn’t this implied by the previous section?

  14. Response: Status: 200 OK??? Is this suppose to represent a header? There is no status header.

    It should be written in text so its not confusing (or even HTTP/1.1 200 OK, but thats look weird and

    assumes HTTP 1.1)

  15. “Facility resource not found or unavailable”: how is ‘unavailable’ defined, and how does it differ

    from not found… should 404 be used for both? or maybe just remove ‘unavailable’?

  16. I think this has been mentioned already. Do we want ‘{ “facility”: { … }’ ? I haven’t seen it used

    anywhere else.

  17. Update a facility: We don’t need to say “not a partial update”, people are not expecting it to be.

    If we were doing partial updates, then we could have mentioned it.

  18. “The body can’t be empty and must include at least the name attribute”: I’m not sure about this.

    Is ID not required? Should it be assigned if not present?

  19. It seems we are using RFC 2119 some places, and other places not. Lets decide if we want it.

    (hint: we want it).

2

Morten,

About to hop on a plane so unfortunately won’t be able to join the call.

Thanks for the comments. Please see responses inline:

Hi guys

In preparation for the call today, I have quickly gone through the spec at facilityregistry.org and have some comments, some are just simple mistakes that needs to be fixed, and others could be points for disussion…

  1. It says 1.0 on http://facilityregistry.org/ already, maybe it should say DRAFT?

Please discuss on the call, let me know what you decide and I’ll update.

  1. HTTP Status Codes: I don’t like that we are specifying what the codes mean, but if we do

lets at least update them so that they are correct with regards to responses, e.g.

201 Created should return the body.

(I really don’t like that it in the spec)

  1. Success: Again we are saying that it return 200 OK for success?
  1. Authentication: Please stop saying ‘token’

I thought I had removed all of this. I see I forgot to remove this from the authenticatoin section. Will update.

  1. Authentication: Please just point to where basic auth is defined, don’t give a step-by-step

instruction on how to do it.

Sure.

  1. Versioning: We are linking to http://semver.org, but which version are we targetting? there are

multiple versions. If we are linking to a page describing it, do we need to also describe it ourselves?

  1. Facility Object: single quotes are not legal JSON!

Will update.

  1. Extended Properties: I’m very confused what we should do about merging here. Should we also store

potentially stale data from other providers? I assume not?

  1. Identifier Properties: Same here. Are we suppose to merge this data? if new identifiers are included in

stream? or do we only care about those that are important to us? If registry A added the identifier, is

registry B allowed to change it?

This has been in the spec for months.

  1. SORTING: Is /facilities.json?sortAsc=properties.MySuperProperty allowed here? or only core props?

I think we decided any proprety is sortable without the need to put properties in front. If you have time to discuss on the call please do and let me know what’s decided.

  1. PAGINATION: I think ?limit=off looks horrible. We are giving another meaning to the limit field, does

this mean paging is off? what about offset? is ?limit=off&offset=10 allowed? if we want to re-use the

limit field, maybe limit=0 would be better?

This is what was agreed on the last call.

  1. FILTERING FACILITIES: I assume people have agreed on this format? it doesn’t look very nice.

Please propose something better. Again this has been in the issues for a long time and was approved with voting.

  1. FILTER BY ACTIVE STATUS: why is this needed? isn’t this implied by the previous section?
  1. Response: Status: 200 OK??? Is this suppose to represent a header? There is no status header.

It should be written in text so its not confusing (or even HTTP/1.1 200 OK, but thats look weird and

assumes HTTP 1.1)

  1. “Facility resource not found or unavailable”: how is ‘unavailable’ defined, and how does it differ

from not found… should 404 be used for both? or maybe just remove ‘unavailable’?

  1. I think this has been mentioned already. Do we want ‘{ “facility”: { … }’ ? I haven’t seen it used

anywhere else.

So are you proposing always keeping the plurarl facilities?

  1. Update a facility: We don’t need to say “not a partial update”, people are not expecting it to be.

If we were doing partial updates, then we could have mentioned it.

  1. “The body can’t be empty and must include at least the name attribute”: I’m not sure about this.

Is ID not required? Should it be assigned if not present?

You mean UUID or ID (new sense of the word). UUID should be able to be passed or user generated.

···

On Thursday, March 7, 2013, Morten Olav Hansen wrote:

  1. It seems we are using RFC 2119 some places, and other places not. Lets decide if we want it.

(hint: we want it).

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

3

As per Matt’s comment about a UUID being either provided or generated by the server, that sounds good to me. Perhaps we should consider a line saying the server needs to generate it if it’s not provided?

Cheers,

Chris

···

On 7 March 2013 15:20, Matt Berg mlberg@gmail.com wrote:

Morten,

About to hop on a plane so unfortunately won’t be able to join the call.

Thanks for the comments. Please see responses inline:

On Thursday, March 7, 2013, Morten Olav Hansen wrote:

Hi guys

In preparation for the call today, I have quickly gone through the spec at facilityregistry.org and have some comments, some are just simple mistakes that needs to be fixed, and others could be points for disussion…

  1. It says 1.0 on http://facilityregistry.org/ already, maybe it should say DRAFT?

Please discuss on the call, let me know what you decide and I’ll update.

  1. HTTP Status Codes: I don’t like that we are specifying what the codes mean, but if we do
lets at least update them so that they are correct with regards to responses, e.g.

201 Created should return the body.

(I really don't like that it in the spec)
  1. Success: Again we are saying that it return 200 OK for success?
  1. Authentication: Please stop saying ‘token’

I thought I had removed all of this. I see I forgot to remove this from the authenticatoin section. Will update.

  1. Authentication: Please just point to where basic auth is defined, don’t give a step-by-step
instruction on how to do it.

Sure.

  1. Versioning: We are linking to http://semver.org, but which version are we targetting? there are
multiple versions. If we are linking to a page describing it, do we need to also describe it ourselves?
  1. Facility Object: single quotes are not legal JSON!

Will update.

  1. Extended Properties: I’m very confused what we should do about merging here. Should we also store
potentially stale data from other providers? I assume not?
  1. Identifier Properties: Same here. Are we suppose to merge this data? if new identifiers are included in
stream? or do we only care about those that are important to us? If registry A added the identifier, is

registry B allowed to change it?

This has been in the spec for months.

  1. SORTING: Is /facilities.json?sortAsc=properties.MySuperProperty allowed here? or only core props?

I think we decided any proprety is sortable without the need to put properties in front. If you have time to discuss on the call please do and let me know what’s decided.

  1. PAGINATION: I think ?limit=off looks horrible. We are giving another meaning to the limit field, does
this mean paging is off? what about offset? is ?limit=off&offset=10 allowed? if we want to re-use the

limit field, maybe limit=0 would be better?

This is what was agreed on the last call.

  1. FILTERING FACILITIES: I assume people have agreed on this format? it doesn’t look very nice.

Please propose something better. Again this has been in the issues for a long time and was approved with voting.

  1. FILTER BY ACTIVE STATUS: why is this needed? isn’t this implied by the previous section?
  1. Response: Status: 200 OK??? Is this suppose to represent a header? There is no status header.
It should be written in text so its not confusing (or even HTTP/1.1 200 OK, but thats look weird and

assumes HTTP 1.1)
  1. “Facility resource not found or unavailable”: how is ‘unavailable’ defined, and how does it differ
from not found.. should 404 be used for both? or maybe just remove 'unavailable'?
  1. I think this has been mentioned already. Do we want ‘{ “facility”: { … }’ ? I haven’t seen it used
anywhere else.

So are you proposing always keeping the plurarl facilities?

  1. Update a facility: We don’t need to say “not a partial update”, people are not expecting it to be.
If we were doing partial updates, then we could have mentioned it.
  1. “The body can’t be empty and must include at least the name attribute”: I’m not sure about this.
Is ID not required? Should it be assigned if not present?

You mean UUID or ID (new sense of the word). UUID should be able to be passed or user generated.

  1. It seems we are using RFC 2119 some places, and other places not. Lets decide if we want it.
(hint: we want it).

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

4

8. Extended Properties: I'm very confused what we should do about merging

here. Should we also store
potentially stale data from other providers? I assume not?

9. Identifier Properties: Same here. Are we suppose to merge this data?
if new identifiers are included in
stream? or do we only care about those that are important to us? If
registry A added the identifier, is
registry B allowed to change it?

This has been in the spec for months.

Ok, sorry. I can't find anything about persisting properties from other
registries in the spec. Especially for the extended properties block, I
assume we are not persisting? we don't have an owner for the properties, so
we will have no idea who generated them. I have been assuming we are NOT
merging this block, I just wanted it written down.

10. SORTING: Is /facilities.json?sortAsc=properties.MySuperProperty

allowed here? or only core props?

I think we decided any proprety is sortable without the need to put
properties in front. If you have time to discuss on the call please do and
let me know what's decided.

I think is too confusing. What about { "name": "My Name", properties: {
"name": "Another Name" } } ?

11. PAGINATION: I think ?limit=off looks horrible. We are giving another

meaning to the limit field, does
this mean paging is off? what about offset? is ?limit=off&offset=10
allowed? if we want to re-use the
limit field, maybe limit=0 would be better?

This is what was agreed on the last call.

I hope we can undo that. Its not a biggie, but it should be talked about.
Or at least the spec updated to more clearly state what it means.

16. I think this has been mentioned already. Do we want '{ "facility": {

... }' ? I haven't seen it used

anywhere else.

So are you proposing always keeping the plurarl facilities?

No, I'm proposing that instead of having { "facility": { "name": "..." } },
we have { "name": "..." }.

18. "The body can’t be empty and must include at least the name

attribute": I'm not sure about this.
Is ID not required? Should it be assigned if not present?

You mean UUID or ID (new sense of the word). UUID should be able to be
passed or user generated.

I wasn't clear here. I mean for update, not for create. Any facility that
is being updated should already have an UUID, right? so creating on
on-demand would be the wrong behavior. Name and ID should be required I
think.

···

--
Morten

19. It seems we are using RFC 2119 some places, and other places not.
Lets decide if we want it.
(hint: we want it).

--
You received this message because you are subscribed to the Google
Groups "Facility Registry" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to facility-registry+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups
"Facility Registry" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to facility-registry+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the
Google Groups "Facility Registry" group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/facility-registry/0hg-bMizaVU/unsubscribe?hl=en
.
To unsubscribe from this group and all its topics, send an email to
facility-registry+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

5

Hi,

Could someone send me a link to the hangout if a call is happening today?

Thanks,

Mike

···

On Thu, Mar 7, 2013 at 8:09 AM, Morten Olav Hansen mortenoh@gmail.com wrote:

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

–
Mike

  1. Extended Properties: I’m very confused what we should do about merging here. Should we also store
potentially stale data from other providers? I assume not?
  1. Identifier Properties: Same here. Are we suppose to merge this data? if new identifiers are included in
stream? or do we only care about those that are important to us? If registry A added the identifier, is

registry B allowed to change it?

This has been in the spec for months.

Ok, sorry. I can’t find anything about persisting properties from other registries in the spec. Especially for the extended properties block, I assume we are not persisting? we don’t have an owner for the properties, so we will have no idea who generated them. I have been assuming we are NOT merging this block, I just wanted it written down.

  1. SORTING: Is /facilities.json?sortAsc=properties.MySuperProperty allowed here? or only core props?

I think we decided any proprety is sortable without the need to put properties in front. If you have time to discuss on the call please do and let me know what’s decided.

I think is too confusing. What about { “name”: “My Name”, properties: { “name”: “Another Name” } } ?

  1. PAGINATION: I think ?limit=off looks horrible. We are giving another meaning to the limit field, does
this mean paging is off? what about offset? is ?limit=off&offset=10 allowed? if we want to re-use the

limit field, maybe limit=0 would be better?

This is what was agreed on the last call.

I hope we can undo that. Its not a biggie, but it should be talked about. Or at least the spec updated to more clearly state what it means.

  1. I think this has been mentioned already. Do we want ‘{ “facility”: { … }’ ? I haven’t seen it used
anywhere else.

So are you proposing always keeping the plurarl facilities?

No, I’m proposing that instead of having { “facility”: { “name”: “…” } }, we have { “name”: “…” }.

  1. “The body can’t be empty and must include at least the name attribute”: I’m not sure about this.
Is ID not required? Should it be assigned if not present?

You mean UUID or ID (new sense of the word). UUID should be able to be passed or user generated.

I wasn’t clear here. I mean for update, not for create. Any facility that is being updated should already have an UUID, right? so creating on on-demand would be the wrong behavior. Name and ID should be required I think.

–

Morten

  1. It seems we are using RFC 2119 some places, and other places not. Lets decide if we want it.
(hint: we want it).

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

–

You received this message because you are subscribed to a topic in the Google Groups “Facility Registry” group.

To unsubscribe from this topic, visit https://groups.google.com/d/topic/facility-registry/0hg-bMizaVU/unsubscribe?hl=en.

To unsubscribe from this group and all its topics, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

6

Kelly usually sends it out just before it happens…

···

–
Morten

On Thu, Mar 7, 2013 at 6:06 PM, Mike White mwhite@dimagi.com wrote:

Hi,

Could someone send me a link to the hangout if a call is happening today?

Thanks,

Mike

–

You received this message because you are subscribed to a topic in the Google Groups “Facility Registry” group.

To unsubscribe from this topic, visit https://groups.google.com/d/topic/facility-registry/0hg-bMizaVU/unsubscribe?hl=en.

To unsubscribe from this group and all its topics, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

On Thu, Mar 7, 2013 at 8:09 AM, Morten Olav Hansen mortenoh@gmail.com wrote:

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

–

Mike

  1. Extended Properties: I’m very confused what we should do about merging here. Should we also store
potentially stale data from other providers? I assume not?
  1. Identifier Properties: Same here. Are we suppose to merge this data? if new identifiers are included in
stream? or do we only care about those that are important to us? If registry A added the identifier, is

registry B allowed to change it?

This has been in the spec for months.

Ok, sorry. I can’t find anything about persisting properties from other registries in the spec. Especially for the extended properties block, I assume we are not persisting? we don’t have an owner for the properties, so we will have no idea who generated them. I have been assuming we are NOT merging this block, I just wanted it written down.

  1. SORTING: Is /facilities.json?sortAsc=properties.MySuperProperty allowed here? or only core props?

I think we decided any proprety is sortable without the need to put properties in front. If you have time to discuss on the call please do and let me know what’s decided.

I think is too confusing. What about { “name”: “My Name”, properties: { “name”: “Another Name” } } ?

  1. PAGINATION: I think ?limit=off looks horrible. We are giving another meaning to the limit field, does
this mean paging is off? what about offset? is ?limit=off&offset=10 allowed? if we want to re-use the

limit field, maybe limit=0 would be better?

This is what was agreed on the last call.

I hope we can undo that. Its not a biggie, but it should be talked about. Or at least the spec updated to more clearly state what it means.

  1. I think this has been mentioned already. Do we want ‘{ “facility”: { … }’ ? I haven’t seen it used
anywhere else.

So are you proposing always keeping the plurarl facilities?

No, I’m proposing that instead of having { “facility”: { “name”: “…” } }, we have { “name”: “…” }.

  1. “The body can’t be empty and must include at least the name attribute”: I’m not sure about this.
Is ID not required? Should it be assigned if not present?

You mean UUID or ID (new sense of the word). UUID should be able to be passed or user generated.

I wasn’t clear here. I mean for update, not for create. Any facility that is being updated should already have an UUID, right? so creating on on-demand would be the wrong behavior. Name and ID should be required I think.

–

Morten

  1. It seems we are using RFC 2119 some places, and other places not. Lets decide if we want it.
(hint: we want it).

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

–

You received this message because you are subscribed to the Google Groups “Facility Registry” group.

To unsubscribe from this group and stop receiving emails from it, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

–

You received this message because you are subscribed to a topic in the Google Groups “Facility Registry” group.

To unsubscribe from this topic, visit https://groups.google.com/d/topic/facility-registry/0hg-bMizaVU/unsubscribe?hl=en.

To unsubscribe from this group and all its topics, send an email to facility-registry+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.