Mandatory URL parts?

[ctford]

We've discussed previously the URLs in the spec, and I think have reached the conclusion that they are examples only - #5.

However, the individual facilities URLs seem to imply that an implementation must use the id field when constructing the individual facility URL, which I didn't think was true:

/facilities/<id>.json

Would it be clearer that it's an example if we put the following?

/facilities/0X9OCW3JMV98EYOVN32SGN4II.json

I think the spec is still a bit confusing as to what is an example and what is actually part of the API.

Seems to me that the mandatory things are:

• ?allProperties=
• ?fields=
• ?updatedSince=
• ?active=
• .json
• major version being somewhere in the URL

Is that everyone else's impression? If so, can we call them out explicitly?

[mortenoh]

While it does not necessarily make sense that the exposed ID is the internal db id (or whatever), I do think { id: } should match /facility/, I think that is following a good convention.

We could let that bit be implementation specific.

Morten

On Tue, Dec 18, 2012 at 4:14 PM, Chris Ford notifications@github.comwrote:

We've discussed previously the URLs in the spec, and I think have reached the conclusion that they are examples only - #5https://github.com/facilityregistry/fred-api/issues/5 .

However, the individual facilities URLs seem to imply that an implementation must use the id field when constructing the individual facility URL, which I didn't think was true:

/facilities/.json

Would it be clearer that it's an example if we put the following?

/facilities/0X9OCW3JMV98EYOVN32SGN4II.json

I think the spec is still a bit confusing as to what is an example and what is actually part of the API.

Seems to me that the mandatory things are:

• ?allProperties=
• ?fields=
• ?updatedSince=
• ?active=
• .json
• major version being somewhere in the URL

Is that everyone else's impression? If so, can we call them out explicitly?

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

[ctford]

I think it's good practice to make that relationship intuitive, however, I think that ids should be UUIDs as per Bharti's post (#26), which might make it expedient to have a shorter id visible in the URL.

[mortenoh]

Well, I think its more intuitive that they match. It also makes it possible to re-generate the URL if there is a need.

On Tue, Dec 18, 2012 at 4:43 PM, Chris Ford notifications@github.comwrote:

I think it's good practice to make that relationship intuitive, however, I think that ids should be UUIDs as per Bharti's post (#26https://github.com/facilityregistry/fred-api/issues/26), which might make it expedient to have a shorter id visible in the URL.

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

[ctford]

But are we agreed that we don't want the implied URL template?

If id is urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 or http://www.example.com/facility/3 then the URL documentation /facilities/<id>.json implies that the URL of the facility should be

/facilities/urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66.json

or

/facilities/http://www.example.com/facility/3.json.

I doubt that's the intention?

[mortenoh]

The way I read the spec, is that the ID exposed is the unique system ID, which means its only unique within one system. That together with the URL, makes an external unique ID.

We are already placing extra identifiers in the identifiers: [] block, and one globally unique (UUID?) ID could be placed here.

[ctford]

The original wording of the spec was that the system should never return the same id more than once. That would imply what you're saying, which is that it's unique only within that system.

When I brought up the question of global uniqueness, the spec was clarified to say the id should be universal:

The internal system uid is denoted with “id”. The id most be universally unique.

This does feel inconsistent. After all, why would an internal system id be universally unique, and why would we care about the internal system id at all as a consumer of the API?

Adding an identifier allows identity to be tracked even when URLs change, but if the identifier isn't globally unique and generated in an open way, then migrating facilities between systems won't work anyway. In other words, why bother exposing a non-global id at all?

I think we should require the id be universal, but remove mention of "internal system id". For DHIS2, that would allow us to have a UUID that's exposed as id, but from an internal point of view it would be an additional identifier.

[ctford]

See #45.