search

facilityregistry / fred-api

Facility Registry API Documentation Website
11 stars 4 forks source link

UUID / Url Templating #45

Closed mortenoh closed 11 years ago

mortenoh commented 11 years ago

Chris and I (Morten) are suggesting two new changes to the API.

Encouraging clients to use the provided url is simpler and less-error prone, as well as giving us as API designers more flexibility as to how we link a facilities registry with a broader system.

We would then have two fields, each with a clear purpose and semantics - url for locating a facility, and uuid for identity.

bobjolliffe commented 11 years ago

+1

On 7 March 2013 05:13, Morten Olav Hansen notifications@github.com wrote:

Chris and I (Morten) are suggesting two new changes to the API.

  • The id field is renamed to uuid
  • The uuid field MUST be a valid UUID as per RFC 4122 using the default string representation (in other words, a conventional UUID).
  • If the url of a facility changes, e.g. the registry moves to another domain, then the uuid must remain constant.
  • The url of a facility MAY be structured around the uuid, a system-specific identifier or some other scheme.
  • Clients of the facilities registry MUST use the provided url field and not attempt to calculate the URL themselves from other fields the facility has.
  • This would allow us to have the benefits of UUIDs for migration, federation etc, while making it more self-evident of the intent of the uuid field.

Encouraging clients to use the provided url is simpler and less-error prone, as well as giving us as API designers more flexibility as to how we link a facilities registry with a broader system.

We would then have two fields, each with a clear purpose and semantics - url for locating a facility, and uuid for identity.

  • Chris, Morten

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/45 .

mberg commented 11 years ago

Very similar in spirit to what I was proposing before.

Only proposed addition, should the URL map to something in the identifiers block? Should we make that an explicit requirement?

Otherwise, +1.

Matt

On Thu, Mar 7, 2013 at 11:08 AM, bobjolliffe notifications@github.comwrote:

+1

On 7 March 2013 05:13, Morten Olav Hansen notifications@github.com wrote:

Chris and I (Morten) are suggesting two new changes to the API.

  • The id field is renamed to uuid
  • The uuid field MUST be a valid UUID as per RFC 4122 using the default string representation (in other words, a conventional UUID).
  • If the url of a facility changes, e.g. the registry moves to another domain, then the uuid must remain constant.
  • The url of a facility MAY be structured around the uuid, a system-specific identifier or some other scheme.
  • Clients of the facilities registry MUST use the provided url field and not attempt to calculate the URL themselves from other fields the facility has.
  • This would allow us to have the benefits of UUIDs for migration, federation etc, while making it more self-evident of the intent of the uuid field.

Encouraging clients to use the provided url is simpler and less-error prone, as well as giving us as API designers more flexibility as to how we link a facilities registry with a broader system.

We would then have two fields, each with a clear purpose and semantics - url for locating a facility, and uuid for identity.

  • Chris, Morten

— Reply to this email directly or view it on GitHub< https://github.com/facilityregistry/fred-api/issues/45> .

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/45#issuecomment-14551730 .

bobjolliffe commented 11 years ago

I think Morten and Chris have just put forward another proposal re the uuid which, if accepted, would explicitly make this NOT a requirement. ie. clients should make no assumptions about how the url is formed (other than perhaps that it uses http or https scheme).

On 7 March 2013 10:11, Matt Berg notifications@github.com wrote:

Very similar in spirit to what I was proposing before.

Only proposed addition, should the URL map to something in the identifiers block? Should we make that an explicit requirement?

Otherwise, +1.

Matt

On Thu, Mar 7, 2013 at 11:08 AM, bobjolliffe notifications@github.comwrote:

+1

On 7 March 2013 05:13, Morten Olav Hansen notifications@github.com wrote:

Chris and I (Morten) are suggesting two new changes to the API.

  • The id field is renamed to uuid
  • The uuid field MUST be a valid UUID as per RFC 4122 using the default string representation (in other words, a conventional UUID).
  • If the url of a facility changes, e.g. the registry moves to another domain, then the uuid must remain constant.
  • The url of a facility MAY be structured around the uuid, a system-specific identifier or some other scheme.
  • Clients of the facilities registry MUST use the provided url field and not attempt to calculate the URL themselves from other fields the facility has.
  • This would allow us to have the benefits of UUIDs for migration, federation etc, while making it more self-evident of the intent of the uuid field.

Encouraging clients to use the provided url is simpler and less-error prone, as well as giving us as API designers more flexibility as to how we link a facilities registry with a broader system.

We would then have two fields, each with a clear purpose and semantics

url for locating a facility, and uuid for identity.

  • Chris, Morten

— Reply to this email directly or view it on GitHub< https://github.com/facilityregistry/fred-api/issues/45> .

— Reply to this email directly or view it on GitHub< https://github.com/facilityregistry/fred-api/issues/45#issuecomment-14551730>

.

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/45#issuecomment-14551845 .

mortenoh commented 11 years ago

Yes, no assumption should be made about the url/href field. On 7 Mar 2013 13:25, "bobjolliffe" notifications@github.com wrote:

I think Morten and Chris have just put forward another proposal re the uuid which, if accepted, would explicitly make this NOT a requirement. ie. clients should make no assumptions about how the url is formed (other than perhaps that it uses http or https scheme).

On 7 March 2013 10:11, Matt Berg notifications@github.com wrote:

Very similar in spirit to what I was proposing before.

Only proposed addition, should the URL map to something in the identifiers block? Should we make that an explicit requirement?

Otherwise, +1.

Matt

On Thu, Mar 7, 2013 at 11:08 AM, bobjolliffe notifications@github.comwrote:

+1

On 7 March 2013 05:13, Morten Olav Hansen notifications@github.com wrote:

Chris and I (Morten) are suggesting two new changes to the API.

  • The id field is renamed to uuid
  • The uuid field MUST be a valid UUID as per RFC 4122 using the default string representation (in other words, a conventional UUID).
  • If the url of a facility changes, e.g. the registry moves to another domain, then the uuid must remain constant.
  • The url of a facility MAY be structured around the uuid, a system-specific identifier or some other scheme.
  • Clients of the facilities registry MUST use the provided url field and not attempt to calculate the URL themselves from other fields the facility has.
  • This would allow us to have the benefits of UUIDs for migration, federation etc, while making it more self-evident of the intent of the uuid field.

Encouraging clients to use the provided url is simpler and less-error prone, as well as giving us as API designers more flexibility as to how we link a facilities registry with a broader system.

We would then have two fields, each with a clear purpose and

semantics

url for locating a facility, and uuid for identity.

  • Chris, Morten

— Reply to this email directly or view it on GitHub< https://github.com/facilityregistry/fred-api/issues/45> .

— Reply to this email directly or view it on GitHub<

https://github.com/facilityregistry/fred-api/issues/45#issuecomment-14551730>

.

— Reply to this email directly or view it on GitHub< https://github.com/facilityregistry/fred-api/issues/45#issuecomment-14551845>

.

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/45#issuecomment-14552370 .

ctford commented 11 years ago

I think that it's good practice for URLs to be intuitive, but I think it's better if clients stick to using the url field directly. To me that's simpler and less error prone, as well as giving API designers and implementors more flexibility when linking between things.

The way that DHIS2 does it at the moment is to put the DHIS2 id in the identifiers block, and use that in the URL. That keeps things neat and makes sense for that implementation, but I think it would be a bit complex to have a URL templating rule telling the client which member of the identifiers block to use - better to just let the server make the URL and have the client go where it's directed.

Cheers.

ctford commented 11 years ago

@mortenoh, @mberg, I think you might both have suggested using uuid as a field name at different times in the past. I originally spoke against that, but I've been persuaded. :-)

edjez commented 11 years ago

+1 Lets write specific assumptions that are common sense about the URL without specifying its shape: eg

sunbiz commented 11 years ago

+1 with the new comments from @edjez

mortenoh commented 11 years ago

Agreed.

Morten

On Thu, Mar 7, 2013 at 7:31 PM, edjez notifications@github.com wrote:

+1 Lets write specific assumptions that are common sense about the URL without specifying its shape: eg

  • using the same URL twice or over time should return the same facility (if it still exists)
  • posting a new facility with a UUID means the registry uses it; posting one without makes the registry generate it

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/45#issuecomment-14570767 .

hispbd commented 11 years ago

agreed

rowenaluk commented 11 years ago

+1

carohadad commented 11 years ago

+1

rowenaluk commented 11 years ago

reached consensus on this on the march 7 call. note that the above proposal still allows users to include version numbers (major/minor/etc) in the URL if they want, but does not mandate this.

bobjolliffe commented 11 years ago

agreed (again)

mortenoh commented 11 years ago

I would say it makes sense to include the version number. Since this is the URL of the version you fetched. But of course, it is not mandated.

On Thu, Mar 7, 2013 at 7:38 PM, rowenaluk notifications@github.com wrote:

reached consensus on this on the march 7 call. note that the above proposal still allows users to include version numbers (major/minor/etc) in the URL if they want, but does not mandate this.

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/45#issuecomment-14571159 .

jwishnie commented 11 years ago

+1

This is excellent. It nicely balances the value of standardization of ID for federation/merging, with the desire/need for flexibility in implementation.

The requirements around URLs (that the same URL retrieve the same resource from a given implementation) and explicit LACK of requirements (that URLs may, but are not required to, be patterned on IDs) is very much in line with REST.

mberg commented 11 years ago

Updated please check and let me know if it looks ok.

http://facilityregistry.org/#facility-resource

bobjolliffe commented 11 years ago

Hi Matt

A few points ...

Firstly we discussed a lot on the previous call the authenticity of the rst document vs the new carte site. I think most of us were of the view that ther rst document is definitive and that the carte site would be generated from that. I don't see updates there.

I don't think the wikipedia reference is necessary. Its sufficient to refer to rfc 4122.

Suggest changing: "The UUID for a facility should remain constant and should never be changed. eg) the URL of the facility changes" to "The UUID should be permanently associated with the facility and should not be changed in response to the name or href properties being changed. Multiple compliant registries having an entry for a facility should use the same uuid to identify the particular facility."

On the href section: "Clients of the facilities registry MUST .." On reflection I think this is a bit strong. The spec can only recommend how clients should behave in this respect. Clients should not assume any structural relationship between the href and other properties and identifiers.

Bob

On 13 March 2013 12:39, Matt Berg notifications@github.com wrote:

Updated please check and let me know if it looks ok.

http://facilityregistry.org/#facility-resource

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/45#issuecomment-14838742 .