A few comments about the spec at facilityregistry.org

[Morten Olav Hansen]

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).

[Matt Berg]

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. 

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'

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

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

instruction on how to do it.

Sure.

 

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!

Will update. 

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.  

 

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.

 

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. 

 

12. 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.

 

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.

So are you proposing always keeping the plurarl facilities?

 

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?

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

 

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-regis...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Chris Ford]

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

[Morten Olav Hansen]

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-regis...@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-regis...@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-regis...@googlegroups.com.

[Mike White]

Hi,

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

Thanks,

Mike

Mike

[Morten Olav Hansen]

Kelly usually sends it out just before it happens..

--
Morten