Some uncensored comments

Legacy facility-registry
1

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?

  2. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)

  3. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…

  4. FOSAID ?

  5. Facility.properties, assume these are just key-value pairs? (attributes, basically)

  6. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user[]=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…

  7. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)

  8. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.

  9. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)

  10. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8

  11. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?

  12. Are they also using POST for updating? not PUT? seems bad… what about PATCH?

  13. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?

  14. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?

  15. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better

  16. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10

  17. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

2

These are great! All comments welcome!

···

On Thursday, November 8, 2012, Bob Jolliffe wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

3

I must say: I really love the spirit and direction of these conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I’m involved with began to grow (OpenMRS), one of the hard things we grappled to get right was finding the right balance between disputes on the details (what color should the bike shed be colored?) vs. the fundamentally important design questions.

One of the things that ended up working well for that community at least, was timeboxing the debates for a given release of a design/specification and creating ample opportunity to queue up concerns for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I suspect this will become challenging to manage, especially in the infancy of the project.

-Paul

···

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

4

The critiques offer great specificity for the tech team to consider. Regarding the process for managing an expected growth in community comments, I hope this is something we can cover in broader discussion next week.

Best,

Kelly

···

On Thu, Nov 8, 2012 at 8:46 PM, Paul Biondich pbiondic@regenstrief.org wrote:

I must say: I really love the spirit and direction of these conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I’m involved with began to grow (OpenMRS), one of the hard things we grappled to get right was finding the right balance between disputes on the details (what color should the bike shed be colored?) vs. the fundamentally important design questions.

One of the things that ended up working well for that community at least, was timeboxing the debates for a given release of a design/specification and creating ample opportunity to queue up concerns for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I suspect this will become challenging to manage, especially in the infancy of the project.

-Paul

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

–

5

Managing comments and suggestions in a standards project is a bit different to an open source software project. There are quite a few similarities but I think some of the rationale and workflow is different - the purpose is not just to produce an artefact but also to establish input and output legitimacy around it.

The input to this process are the comments themselves … in ISO for example these are sent in through standard templates by national member bodies. Generally a horrible process which I wouldn’t advocate. In OASIS (which I think does this better) the comments are funnelled through a made for purpose comments mailing list. So anybody anywhere can make a comment on the spec by posting to this list.

The task of the committee is to “dispose” of comments. Comments can be disposed of in different ways, much like issue tracking in a software project, but one important way that a comment is disposed of is that it results in an instruction to the editor. I think this role an editor is really important and I was happy to see it highlighted in the “one document” approach I was reading about in next weeks pre-workshop reading. That was a good read.

I don’t think that we should all be hacking over the document.

I think we will need to set up a process for receiving and processing comments and relaying instructions to the editor (currently Matt).

···

Minutes of meetings should tabulate which comments have been disposed of and how.

Its helpful to have a meeting chair who is maybe separate from the editor.

Some of the above formalities start to work better as the process matures (ie we have a 1.0) but we can and should start building up the practices now.

On 9 November 2012 04:19, Kelly Keisling keisling.kelly@gmail.com wrote:

The critiques offer great specificity for the tech team to consider. Regarding the process for managing an expected growth in community comments, I hope this is something we can cover in broader discussion next week.

Best,

Kelly

On Thu, Nov 8, 2012 at 8:46 PM, Paul Biondich pbiondic@regenstrief.org wrote:

I must say: I really love the spirit and direction of these conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I’m involved with began to grow (OpenMRS), one of the hard things we grappled to get right was finding the right balance between disputes on the details (what color should the bike shed be colored?) vs. the fundamentally important design questions.

One of the things that ended up working well for that community at least, was timeboxing the debates for a given release of a design/specification and creating ample opportunity to queue up concerns for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I suspect this will become challenging to manage, especially in the infancy of the project.

-Paul

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

–

–

6

We want to simultaneously minimise bike-shedding, and avoid releasing stuff that we later need to change. To do that, I think we should really be concentrating on producing a minimal viable API and making it robust. The more contentious details we include, the greater the chance we will or want to break backwards compatibility in the future.

For example we could do some of:

  • Explicitly require consumers of the API to ignore fields they do not recognise, which will allow us to expand the API relatively painlessly.
  • Support only a single format ie either JSON or XML. My preference is JSON, but one format is simpler than two.
  • Avoid hierarchies.
  • Avoid filters, counts, sorting etc.
  • Avoid text search.

I’m not aware of which of these are driven by current use cases, and which ones are immediately necessary.

In response to the comments Bob passed on:

  1. Agreed. URLs are not GUIDs, though they are URIs. Perhaps “link” (as in Atom) would be a better choice than “guid”? Or “url”?

  2. I don’t understand the snippets either. Wouldn’t it be easier to have a collection called “identifiers” that can contain multiple entries rather than top-level keys with an “identifier=yes” key?

  3. I’m not sure either of what admin_unit is, though perhaps if it’s related to hierarchies we can leave it out of the current version.

  4. I think that POST is fine. If we want PUT semantics that’s ok too, but it only works if the client can determine the facility’s URL. PATCH is a little unconventional for my tastes, and doesn’t seem to give us any useful semantics.

  5. Another place that the guid/url issue needs clearing up…

  6. Why do we want the $ prefix in the API?

  7. I don’t think that count was intended to be an id, just part of a URL.

Perhaps some of the examples would have more power if we had complete JSON/XML documents instead of just snippets?

Cheers,

Chris

···

Minutes of meetings should tabulate which comments have been disposed of and how.

Its helpful to have a meeting chair who is maybe separate from the editor.

Some of the above formalities start to work better as the process matures (ie we have a 1.0) but we can and should start building up the practices now.

On 9 November 2012 04:19, Kelly Keisling keisling.kelly@gmail.com wrote:

The critiques offer great specificity for the tech team to consider. Regarding the process for managing an expected growth in community comments, I hope this is something we can cover in broader discussion next week.

Best,

Kelly

On Thu, Nov 8, 2012 at 8:46 PM, Paul Biondich pbiondic@regenstrief.org wrote:

I must say: I really love the spirit and direction of these conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I’m involved with began to grow (OpenMRS), one of the hard things we grappled to get right was finding the right balance between disputes on the details (what color should the bike shed be colored?) vs. the fundamentally important design questions.

One of the things that ended up working well for that community at least, was timeboxing the debates for a given release of a design/specification and creating ample opportunity to queue up concerns for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I suspect this will become challenging to manage, especially in the infancy of the project.

-Paul

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

–

–

7

We want to simultaneously minimise bike-shedding, and avoid releasing
stuff that we later need to change. To do that, I think we should really be
concentrating on producing a minimal viable API and making it robust. The
more contentious details we include, the greater the chance we will or want
to break backwards compatibility in the future.

I'm not sure of the bike-shedding metaphor but it sounds like something we
want to avoid :slight_smile: This is a reference to the earlier comment on paint
colours?

For example we could do some of:

   - Explicitly require consumers of the API to ignore fields they do not
   recognise, which will allow us to expand the API relatively painlessly.
   - Support only a single format ie either JSON or XML. My preference is
   JSON, but one format is simpler than two.
   - Avoid hierarchies.
   - Avoid filters, counts, sorting etc.
   - Avoid text search.

I'm not aware of which of these are driven by current use cases, and which
ones are immediately necessary.

I am in favour of all of the above for all of the reasons you have

mentioned. We have actually had the discussion some months back about
trying to specify multiple formats in one go and we did actually reach
agreement that as a first pass we would specify just one. And we agreed
that it would be XML format (with the provision that implementations may
well develop alternatives which we could look at formalizing in a later
iteration). My preference for XML was because the tooling is better for
formally describing the grammar and we would use xslt quite extensively for
importing and exporting different formats. Some of this early agreement
seems to have got lost in the latest flurry of activity on the 0.9
document. We could reopen the discussion about preferred formats but agree
that we should focus on one.

This was the reason I started out trying to propose a facility schema with
examples which we could get some consensus around .. a process which was
going fairly well I thought.

Related to the above, I have also raised some reservations about georss. I
*think* the purpose of rss (geo and otherwise) is to provide summary
information in a feed, typically with links to the "full" representation,
article, blog post or what have you. I am not sure it is the ideal
starting point wrapper for a complete encapsulation of facilities.

The simpler problem of how do we represent just one facility gets lost.
For example when we POST what do we POST. An rss item? When we retrieve
an individual facility, what do we retrieve? An rss feed with one item?

What I was hoping we would do is reach fairly rapid agreement on this
representation (on which we have made some progress) and then focus on the
minimal API required to meet the known and articulated use cases which we
have to achieve specific interoperability goals.

In response to the comments Bob passed on:

2. Agreed. URLs are not GUIDs, though they *are* URIs. Perhaps "link" (as
in Atom) would be a better choice than "guid"? Or "url"?

3. I don't understand the <FOSAID> snippets either. Wouldn't it be easier
to have a collection called "identifiers" that can contain multiple entries
rather than top-level keys with an "identifier=yes" key?

That was my initial proposal. I still think it is better, but can live

with the semantics of "identifier=yes"

5. I'm not sure either of what admin_unit is, though perhaps if it's
related to hierarchies we can leave it out of the current version.

11. I think that POST is fine. If we want PUT semantics that's ok too, but
it only works if the client can determine the facility's URL. PATCH is a
little unconventional for my tastes, and doesn't seem to give us any useful
semantics.

12. Another place that the guid/url issue needs clearing up...

13. Why do we want the $ prefix in the API?

14. I don't think that count was intended to be an id, just part of a URL.

Perhaps some of the examples would have more power if we had complete
JSON/XML documents instead of just snippets?

Agree. This was the process I was starting at

GitHub - bobjolliffe/facility_reference and described at
Facility Registry Specification Proposal - Google Docs
.

Regards
Bob

···

On 9 November 2012 12:21, Chris Ford <cford@thoughtworks.com> wrote:

Cheers,

Chris

On 9 November 2012 17:21, Bob Jolliffe <bobjolliffe@gmail.com> wrote:

Managing comments and suggestions in a standards project is a bit
different to an open source software project. There are quite a few
similarities but I think some of the rationale and workflow is different -
the purpose is not just to produce an artefact but also to establish input
and output legitimacy around it.

The input to this process are the comments themselves ... in ISO for
example these are sent in through standard templates by national member
bodies. Generally a horrible process which I wouldn't advocate. In OASIS
(which I think does this better) the comments are funnelled through a made
for purpose comments mailing list. So anybody anywhere can make a comment
on the spec by posting to this list.

The task of the committee is to "dispose" of comments. Comments can be
disposed of in different ways, much like issue tracking in a software
project, but one important way that a comment is disposed of is that it
results in an instruction to the editor. I think this role an editor is
really important and I was happy to see it highlighted in the "one
document" approach I was reading about in next weeks pre-workshop reading.
That was a good read.

I don't think that we should all be hacking over the document.

I think we will need to set up a process for receiving and processing
comments and relaying instructions to the editor (currently Matt).

Minutes of meetings should tabulate which comments have been disposed of
and how.

Its helpful to have a meeting chair who is maybe separate from the editor.

Some of the above formalities start to work better as the process matures
(ie we have a 1.0) but we can and should start building up the practices
now.

On 9 November 2012 04:19, Kelly Keisling <keisling.kelly@gmail.com>wrote:

The critiques offer great specificity for the tech team to consider.
Regarding the process for managing an expected growth in community
comments, I hope this is something we can cover in broader discussion next
week.

Best,
Kelly

On Thu, Nov 8, 2012 at 8:46 PM, Paul Biondich <pbiondic@regenstrief.org>wrote:

I must say: I really love the spirit and direction of these
conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I'm involved with
began to grow (OpenMRS), one of the hard things we grappled to get right
was finding the right balance between disputes on the details (what color
should the bike shed be colored?) vs. the fundamentally important design
questions.

One of the things that ended up working well for that community at
least, was timeboxing the debates for a given release of a
design/specification and creating ample opportunity to queue up concerns
for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I
suspect this will become challenging to manage, especially in the infancy
of the project.

-Paul

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe <bobjolliffe@gmail.com>wrote:

Hi, I've attached some comments below from one of our web developers.
I was hoping to go through them and present some sanitised summary but I
am running short of time so rather than sit on them I share below in their
entirety.

They are a bit raw because they were really just sent to me but we
will be thick skinned :-). All comments are valuable. Where they are
incorrect just means we have not explained well enough yet. Where they are
correct we should address

Regards
Bob

Hi Bob,

Some comments.. I think parts of the spec is really bad, and not
updated.. so not sure if it all applies.. seems like too many people are
doing edits, and adding what they want.. it should probably have a editor!

0. Do they want this to be a RESTful API? or are they just creating an
API?

1. What is the facility.version field used for? will it also be used
for collections of objects? (seems like it will be duplicated, since you
are probably asking for a specific version?)

2. Facility.guid seems either like an unfortunate name for it, or just
completely wrong altogheter. Will the guid actually link to something
useful? will that page provide more information, or is it used more like
XML namespaces? if you say the term GUID to developer (especially MS
developers I guess), they will not think about URLs. I see that in some of
the XML examples all the way down.. url = guid..

3. FOSAID ?

4. Facility.properties, assume these are just key-value pairs?
(attributes, basically)

5. What is the admin_unit field? I don't see this in any JSON example?
?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but
seems like it shouldn't be in 0.9, so I guess its still being developed..

6. "Returns HTTP Response 200, 401 or 404 along with a human readable
error message." I guess 200 should be taken out of that:)

7. "Optional Verbose Error messages", can more_info be both a URL, and
a free-form text field? should it use the same key? Would be nice to also
get the error-code, so that you don't need to parse it out from the URL.

8. Versioning: most of the big guys uses headers for this now. From a
REST purity standpoint, having it in the header makes the most sense, and
if "jr developers can't use them" (I saw this mentioned on the list), who
cares (if they don't know about http headers, how can they set a
content-type?)

9. Adding: it should return 201 Created, and also the Location: <url
of new facility> as a header. Of course, if they don't understand headers..
we will have the same problem here as in pt 8

10. /facility/<facility_id>, what is facility ID? any identifier on
the list? or just a guid? what if there are collisions?

11. Are they also using POST for updating? not PUT? seems bad.. what
about PATCH?

12. GET /facilities/<guid>.json/xml, would not work well with the way
GUIDs are defined today... what about other identifiers?

13. Filtering options: I know they are using a backend that almost
requires this, but do we really have to use the ugly $filter_option syntax?
what are the advantage from just using gt/le etc?

14. /facilities/count.json, this really breaks REST (count is ID??),
/facilities?countOnly=true or something would be much better

15. /facilities/count.json?beds=10, same here, you search for beds=10,
but tell it with another query string saying that you only want the count.
/facilities?countOnly=true&beds=10

16. ?pages=all = returns all pages, is this meant to be a boolean? bad
naming.. what are the options here? can you do pages=1,2,3,4 ? probably
not? I like our ?paging=false better......

--

--

--

--

--

8

Bob,

At the end of the last call, we discussed just sticking with stock XML and JSON as initial standards. The implementer could optionally also serve us georss and geojson.

Thanks,

Matt

···

On Fri, Nov 9, 2012 at 7:56 AM, Bob Jolliffe bobjolliffe@gmail.com wrote:

On 9 November 2012 12:21, Chris Ford cford@thoughtworks.com wrote:

–

We want to simultaneously minimise bike-shedding, and avoid releasing stuff that we later need to change. To do that, I think we should really be concentrating on producing a minimal viable API and making it robust. The more contentious details we include, the greater the chance we will or want to break backwards compatibility in the future.

I’m not sure of the bike-shedding metaphor but it sounds like something we want to avoid :slight_smile: This is a reference to the earlier comment on paint colours?

For example we could do some of:

  • Explicitly require consumers of the API to ignore fields they do not recognise, which will allow us to expand the API relatively painlessly.
  • Support only a single format ie either JSON or XML. My preference is JSON, but one format is simpler than two.
  • Avoid hierarchies.
  • Avoid filters, counts, sorting etc.
  • Avoid text search.

I’m not aware of which of these are driven by current use cases, and which ones are immediately necessary.

I am in favour of all of the above for all of the reasons you have mentioned. We have actually had the discussion some months back about trying to specify multiple formats in one go and we did actually reach agreement that as a first pass we would specify just one. And we agreed that it would be XML format (with the provision that implementations may well develop alternatives which we could look at formalizing in a later iteration). My preference for XML was because the tooling is better for formally describing the grammar and we would use xslt quite extensively for importing and exporting different formats. Some of this early agreement seems to have got lost in the latest flurry of activity on the 0.9 document. We could reopen the discussion about preferred formats but agree that we should focus on one.

This was the reason I started out trying to propose a facility schema with examples which we could get some consensus around … a process which was going fairly well I thought.

Related to the above, I have also raised some reservations about georss. I think the purpose of rss (geo and otherwise) is to provide summary information in a feed, typically with links to the “full” representation, article, blog post or what have you. I am not sure it is the ideal starting point wrapper for a complete encapsulation of facilities.

The simpler problem of how do we represent just one facility gets lost. For example when we POST what do we POST. An rss item? When we retrieve an individual facility, what do we retrieve? An rss feed with one item?

What I was hoping we would do is reach fairly rapid agreement on this representation (on which we have made some progress) and then focus on the minimal API required to meet the known and articulated use cases which we have to achieve specific interoperability goals.

In response to the comments Bob passed on:

  1. Agreed. URLs are not GUIDs, though they are URIs. Perhaps “link” (as in Atom) would be a better choice than “guid”? Or “url”?
  1. I don’t understand the snippets either. Wouldn’t it be easier to have a collection called “identifiers” that can contain multiple entries rather than top-level keys with an “identifier=yes” key?

That was my initial proposal. I still think it is better, but can live with the semantics of “identifier=yes”

  1. I’m not sure either of what admin_unit is, though perhaps if it’s related to hierarchies we can leave it out of the current version.
  1. I think that POST is fine. If we want PUT semantics that’s ok too, but it only works if the client can determine the facility’s URL. PATCH is a little unconventional for my tastes, and doesn’t seem to give us any useful semantics.
  1. Another place that the guid/url issue needs clearing up…
  1. Why do we want the $ prefix in the API?
  1. I don’t think that count was intended to be an id, just part of a URL.

Perhaps some of the examples would have more power if we had complete JSON/XML documents instead of just snippets?

Agree. This was the process I was starting at https://github.com/bobjolliffe/facility_reference and described at https://docs.google.com/document/d/1Xkr5vioqjzyHrgpmKKhWzs8vx1dI9uaQR0ckLFrKI3Y/edit#heading=h.of07mjl5723m.

Regards

Bob

Cheers,

Chris

On 9 November 2012 17:21, Bob Jolliffe bobjolliffe@gmail.com wrote:

Managing comments and suggestions in a standards project is a bit different to an open source software project. There are quite a few similarities but I think some of the rationale and workflow is different - the purpose is not just to produce an artefact but also to establish input and output legitimacy around it.

The input to this process are the comments themselves … in ISO for example these are sent in through standard templates by national member bodies. Generally a horrible process which I wouldn’t advocate. In OASIS (which I think does this better) the comments are funnelled through a made for purpose comments mailing list. So anybody anywhere can make a comment on the spec by posting to this list.

The task of the committee is to “dispose” of comments. Comments can be disposed of in different ways, much like issue tracking in a software project, but one important way that a comment is disposed of is that it results in an instruction to the editor. I think this role an editor is really important and I was happy to see it highlighted in the “one document” approach I was reading about in next weeks pre-workshop reading. That was a good read.

I don’t think that we should all be hacking over the document.

I think we will need to set up a process for receiving and processing comments and relaying instructions to the editor (currently Matt).

–

–

Minutes of meetings should tabulate which comments have been disposed of and how.

Its helpful to have a meeting chair who is maybe separate from the editor.

Some of the above formalities start to work better as the process matures (ie we have a 1.0) but we can and should start building up the practices now.

On 9 November 2012 04:19, Kelly Keisling keisling.kelly@gmail.com wrote:

The critiques offer great specificity for the tech team to consider. Regarding the process for managing an expected growth in community comments, I hope this is something we can cover in broader discussion next week.

Best,

Kelly

On Thu, Nov 8, 2012 at 8:46 PM, Paul Biondich pbiondic@regenstrief.org wrote:

I must say: I really love the spirit and direction of these conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I’m involved with began to grow (OpenMRS), one of the hard things we grappled to get right was finding the right balance between disputes on the details (what color should the bike shed be colored?) vs. the fundamentally important design questions.

One of the things that ended up working well for that community at least, was timeboxing the debates for a given release of a design/specification and creating ample opportunity to queue up concerns for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I suspect this will become challenging to manage, especially in the infancy of the project.

-Paul

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

–

–

9

Thanks all for this feedback.

I agree with Bob’s suggestion of receiving comments then having one person incorporate them into a document vs. editing a live doc. We’re using a google doc now but hope to shift to a more formal approach after this initial release. I’ve started to work on an API website that leverages .rst and github to help manage the process better.

One of the issues is that some of the comments are on points left in the documents as notes / drafts of an idea. Having the agreed upon points in a separate clean document (something I’m working on) I think will be helpful moving forward.

We greatly appreciate the comments though. There are a lot of different approaches to doing RESTful apis so I’m achieving stylistic with everyone might be impossible. However, I’m encouraged by the feedback as it means we’re starting to develop, as Paul pointed out, a community.

Matt

···

On Fri, Nov 9, 2012 at 7:21 AM, Chris Ford cford@thoughtworks.com wrote:

We want to simultaneously minimise bike-shedding, and avoid releasing stuff that we later need to change. To do that, I think we should really be concentrating on producing a minimal viable API and making it robust. The more contentious details we include, the greater the chance we will or want to break backwards compatibility in the future.

For example we could do some of:

  • Explicitly require consumers of the API to ignore fields they do not recognise, which will allow us to expand the API relatively painlessly.
  • Support only a single format ie either JSON or XML. My preference is JSON, but one format is simpler than two.
  • Avoid hierarchies.
  • Avoid filters, counts, sorting etc.
  • Avoid text search.

I’m not aware of which of these are driven by current use cases, and which ones are immediately necessary.

In response to the comments Bob passed on:

  1. Agreed. URLs are not GUIDs, though they are URIs. Perhaps “link” (as in Atom) would be a better choice than “guid”? Or “url”?
  1. I don’t understand the snippets either. Wouldn’t it be easier to have a collection called “identifiers” that can contain multiple entries rather than top-level keys with an “identifier=yes” key?
  1. I’m not sure either of what admin_unit is, though perhaps if it’s related to hierarchies we can leave it out of the current version.
  1. I think that POST is fine. If we want PUT semantics that’s ok too, but it only works if the client can determine the facility’s URL. PATCH is a little unconventional for my tastes, and doesn’t seem to give us any useful semantics.
  1. Another place that the guid/url issue needs clearing up…
  1. Why do we want the $ prefix in the API?
  1. I don’t think that count was intended to be an id, just part of a URL.

Perhaps some of the examples would have more power if we had complete JSON/XML documents instead of just snippets?

Cheers,

Chris

On 9 November 2012 17:21, Bob Jolliffe bobjolliffe@gmail.com wrote:

Managing comments and suggestions in a standards project is a bit different to an open source software project. There are quite a few similarities but I think some of the rationale and workflow is different - the purpose is not just to produce an artefact but also to establish input and output legitimacy around it.

The input to this process are the comments themselves … in ISO for example these are sent in through standard templates by national member bodies. Generally a horrible process which I wouldn’t advocate. In OASIS (which I think does this better) the comments are funnelled through a made for purpose comments mailing list. So anybody anywhere can make a comment on the spec by posting to this list.

The task of the committee is to “dispose” of comments. Comments can be disposed of in different ways, much like issue tracking in a software project, but one important way that a comment is disposed of is that it results in an instruction to the editor. I think this role an editor is really important and I was happy to see it highlighted in the “one document” approach I was reading about in next weeks pre-workshop reading. That was a good read.

I don’t think that we should all be hacking over the document.

I think we will need to set up a process for receiving and processing comments and relaying instructions to the editor (currently Matt).

–

–

Minutes of meetings should tabulate which comments have been disposed of and how.

Its helpful to have a meeting chair who is maybe separate from the editor.

Some of the above formalities start to work better as the process matures (ie we have a 1.0) but we can and should start building up the practices now.

On 9 November 2012 04:19, Kelly Keisling keisling.kelly@gmail.com wrote:

The critiques offer great specificity for the tech team to consider. Regarding the process for managing an expected growth in community comments, I hope this is something we can cover in broader discussion next week.

Best,

Kelly

On Thu, Nov 8, 2012 at 8:46 PM, Paul Biondich pbiondic@regenstrief.org wrote:

I must say: I really love the spirit and direction of these conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I’m involved with began to grow (OpenMRS), one of the hard things we grappled to get right was finding the right balance between disputes on the details (what color should the bike shed be colored?) vs. the fundamentally important design questions.

One of the things that ended up working well for that community at least, was timeboxing the debates for a given release of a design/specification and creating ample opportunity to queue up concerns for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I suspect this will become challenging to manage, especially in the infancy of the project.

-Paul

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

–

–

10

I wasn’t able to attend the last call as I was unwell. What was the rationale behind supporting both XML and JSON instead of picking one?

To me, the YAGNI principle would suggest we minimise what we put out there and therefore reduce the opportunities for inconsistencies, backwards incompatibilities and even disagreements on document structure.

Cheers,

Chris

···

On Fri, Nov 9, 2012 at 7:21 AM, Chris Ford cford@thoughtworks.com wrote:

We want to simultaneously minimise bike-shedding, and avoid releasing stuff that we later need to change. To do that, I think we should really be concentrating on producing a minimal viable API and making it robust. The more contentious details we include, the greater the chance we will or want to break backwards compatibility in the future.

For example we could do some of:

  • Explicitly require consumers of the API to ignore fields they do not recognise, which will allow us to expand the API relatively painlessly.
  • Support only a single format ie either JSON or XML. My preference is JSON, but one format is simpler than two.
  • Avoid hierarchies.
  • Avoid filters, counts, sorting etc.
  • Avoid text search.

I’m not aware of which of these are driven by current use cases, and which ones are immediately necessary.

In response to the comments Bob passed on:

  1. Agreed. URLs are not GUIDs, though they are URIs. Perhaps “link” (as in Atom) would be a better choice than “guid”? Or “url”?
  1. I don’t understand the snippets either. Wouldn’t it be easier to have a collection called “identifiers” that can contain multiple entries rather than top-level keys with an “identifier=yes” key?
  1. I’m not sure either of what admin_unit is, though perhaps if it’s related to hierarchies we can leave it out of the current version.
  1. I think that POST is fine. If we want PUT semantics that’s ok too, but it only works if the client can determine the facility’s URL. PATCH is a little unconventional for my tastes, and doesn’t seem to give us any useful semantics.
  1. Another place that the guid/url issue needs clearing up…
  1. Why do we want the $ prefix in the API?
  1. I don’t think that count was intended to be an id, just part of a URL.

Perhaps some of the examples would have more power if we had complete JSON/XML documents instead of just snippets?

Cheers,

Chris

On 9 November 2012 17:21, Bob Jolliffe bobjolliffe@gmail.com wrote:

Managing comments and suggestions in a standards project is a bit different to an open source software project. There are quite a few similarities but I think some of the rationale and workflow is different - the purpose is not just to produce an artefact but also to establish input and output legitimacy around it.

The input to this process are the comments themselves … in ISO for example these are sent in through standard templates by national member bodies. Generally a horrible process which I wouldn’t advocate. In OASIS (which I think does this better) the comments are funnelled through a made for purpose comments mailing list. So anybody anywhere can make a comment on the spec by posting to this list.

The task of the committee is to “dispose” of comments. Comments can be disposed of in different ways, much like issue tracking in a software project, but one important way that a comment is disposed of is that it results in an instruction to the editor. I think this role an editor is really important and I was happy to see it highlighted in the “one document” approach I was reading about in next weeks pre-workshop reading. That was a good read.

I don’t think that we should all be hacking over the document.

I think we will need to set up a process for receiving and processing comments and relaying instructions to the editor (currently Matt).

–

–

Minutes of meetings should tabulate which comments have been disposed of and how.

Its helpful to have a meeting chair who is maybe separate from the editor.

Some of the above formalities start to work better as the process matures (ie we have a 1.0) but we can and should start building up the practices now.

On 9 November 2012 04:19, Kelly Keisling keisling.kelly@gmail.com wrote:

The critiques offer great specificity for the tech team to consider. Regarding the process for managing an expected growth in community comments, I hope this is something we can cover in broader discussion next week.

Best,

Kelly

On Thu, Nov 8, 2012 at 8:46 PM, Paul Biondich pbiondic@regenstrief.org wrote:

I must say: I really love the spirit and direction of these conversations.

I think you all are doing a way better job on this front.

Dare I say that this is starting to feel like a community? :slight_smile:

A general comment: as another open source community I’m involved with began to grow (OpenMRS), one of the hard things we grappled to get right was finding the right balance between disputes on the details (what color should the bike shed be colored?) vs. the fundamentally important design questions.

One of the things that ended up working well for that community at least, was timeboxing the debates for a given release of a design/specification and creating ample opportunity to queue up concerns for a subsequent iteration.

Seems like the commentary is growing quickly (which is great!), but I suspect this will become challenging to manage, especially in the infancy of the project.

-Paul

On Thu, Nov 8, 2012 at 7:03 PM, Bob Jolliffe bobjolliffe@gmail.com wrote:

Hi, I’ve attached some comments below from one of our web developers. I was hoping to go through them and present some sanitised summary but I am running short of time so rather than sit on them I share below in their entirety.

They are a bit raw because they were really just sent to me but we will be thick skinned :-). All comments are valuable. Where they are incorrect just means we have not explained well enough yet. Where they are correct we should address

Regards

Bob

Hi Bob,

Some comments… I think parts of the spec is really bad, and not updated… so not sure if it all applies… seems like too many people are doing edits, and adding what they want… it should probably have a editor!

  1. Do they want this to be a RESTful API? or are they just creating an API?
  1. What is the facility.version field used for? will it also be used for collections of objects? (seems like it will be duplicated, since you are probably asking for a specific version?)
  1. Facility.guid seems either like an unfortunate name for it, or just completely wrong altogheter. Will the guid actually link to something useful? will that page provide more information, or is it used more like XML namespaces? if you say the term GUID to developer (especially MS developers I guess), they will not think about URLs. I see that in some of the XML examples all the way down… url = guid…
  1. FOSAID ?
  1. Facility.properties, assume these are just key-value pairs? (attributes, basically)
  1. What is the admin_unit field? I don’t see this in any JSON example? ?admin_user=Sud vs ?admin_user=Sud? Seems like a very strange syntax, but seems like it shouldn’t be in 0.9, so I guess its still being developed…
  1. “Returns HTTP Response 200, 401 or 404 along with a human readable error message.” I guess 200 should be taken out of that:)
  1. “Optional Verbose Error messages”, can more_info be both a URL, and a free-form text field? should it use the same key? Would be nice to also get the error-code, so that you don’t need to parse it out from the URL.
  1. Versioning: most of the big guys uses headers for this now. From a REST purity standpoint, having it in the header makes the most sense, and if “jr developers can’t use them” (I saw this mentioned on the list), who cares (if they don’t know about http headers, how can they set a content-type?)
  1. Adding: it should return 201 Created, and also the Location: as a header. Of course, if they don’t understand headers… we will have the same problem here as in pt 8
  1. /facility/<facility_id>, what is facility ID? any identifier on the list? or just a guid? what if there are collisions?
  1. Are they also using POST for updating? not PUT? seems bad… what about PATCH?
  1. GET /facilities/.json/xml, would not work well with the way GUIDs are defined today… what about other identifiers?
  1. Filtering options: I know they are using a backend that almost requires this, but do we really have to use the ugly $filter_option syntax? what are the advantage from just using gt/le etc?
  1. /facilities/count.json, this really breaks REST (count is ID??), /facilities?countOnly=true or something would be much better
  1. /facilities/count.json?beds=10, same here, you search for beds=10, but tell it with another query string saying that you only want the count. /facilities?countOnly=true&beds=10
  1. ?pages=all = returns all pages, is this meant to be a boolean? bad naming… what are the options here? can you do pages=1,2,3,4 ? probably not? I like our ?paging=false better…

–

–

–