UUID / Url Templating

[mortenoh]

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

[bobjolliffe]

+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//issues/45
.

[mberg]

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//issues/45#issuecomment-14551730
.

[bobjolliffe]

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//issues/45#issuecomment-14551845
.

[mortenoh]

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//issues/45#issuecomment-14552370
.

[ctford]

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]

@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]

+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

[sunbiz]

+1 with the new comments from @edjez

[mortenoh]

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//issues/45#issuecomment-14570767
.

[hispbd]

agreed

[rowenaluk]

+1

[carohadad]

+1

[rowenaluk]

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]

agreed (again)

[mortenoh]

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//issues/45#issuecomment-14571159
.

[jwishnie]

+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]

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

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

[bobjolliffe]

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//issues/45#issuecomment-14838742
.