Remove URL structure from the specification

[ctford]

Currently, the collection format includes a URL to each individual facility. Any consumer of the service can take a collection of facilities and follow the URLs to individual facilities.

However, we go further in the current specification, and describe the format of the URL of both the collection and individual facilities, e.g.:

/facilities
/facilities/123

I propose that we don't include URL structure as part of the API contract, thus loosening the coupling between consumer and service a little. Services are still free to use the URL structure if they want, but consumers shouldn't depend on it.

For example, exposing the structure of the URL as part of the contract would prevent anyone from exposing a "mashup" list of facilities from multiple registries.

Rwanda and Uganda might keep track of their own list of facilities, but it could be useful to provide a list of facilities that are involved in a cross-border campaign. If we tell consumers of the API that they can construct URLs of individual facilities from the URL of the collection, this is not possible, because a facility has to be hosted on the same registry as the list.

Allowing arbitrary URLs also gives a way to do filtering, search etc without including it explicitly in the first draft of the API e.g. we could expect all the following URLs to work, so long as they return the correct collection format:

/facility-search?q=foo
http://www.world-wide-fred.com/all
/campaigns/polio-vaccine/participating-facilities

I'd be interested to hear about the advantages of specifying URLs to balance the above points...

[mberg]

Chris,

Can you clarify or provide and example of how the Rwanda/Uganda example would work? I'm a bit confused.

I think a lot REST API's include the nouns involved in service in the contract no?

[ctford]

The current spec seems to assume that the facilities URLs are on the same host as the collection, which limits the ability of people to create their own (standard-compliant) collections.

The spec says that the list of facilities must be made available at a url like so:

http://example.org/facilities

and individual facilities like so:

http://example.org/facilities/123
http://example.org/facilities/456

Let's imagine that both Rwanda and Uganda have facilities registries, which is a possibility. So we end up with facilities that look like this:

http://rwanda.example.org/facilities/123
http://rwanda.example.org/facilities/456
http://rwanda.example.org/facilities/789

http://uganda.example.org/facilities/123
http://uganda.example.org/facilities/456

Let's say that I'm running a study or project that involves some facilities from Rwanda and some from Uganda. I want to expose lists of those facilities I'm working with, and others who might join in:

http://malaria-study.example.org/participants
http://malaria-study.example.org/candidates

These collections return facilities XML that looks something like this:

http://rwanda.example.org/facilities/456 http://uganda.example.org/facilities/456

Except, they can't do that and be conformant with the FRED API as we're locking down the URLs that collections and facilities have to be available at. In fact, if the Ugandan government wanted to make another list that linked to a subset of their own facilities, they couldn't do it and be sure that compliant consumers of the API would understand.

There is a tradeoff between how much structure we want to enforce in the URLs. The more structured we make it, the easier it is to document and talk about, but the less flexible it is. My bias is towards standardising formats and away from standardising URLs.

I think this is a less important point than the discussion over versioning though.

[bobjolliffe]

Chris this is a good example of a point I have made over and over. Examples are just examples - they are always informative and not normative. In fact there is an extreme view that says examples shouldn't appear in a formal spec at all. At best they are informative, at worse they are misleading - save them for the implementation guide. I don't subscribe to that entirely, but we must say what we mean. And keep examples in clearly marked informative boxes. The current document simply says: "URL

Link to the API resource for the facility"

What follows is an example. My interpretation of what is written is that what you have above is perfectly legal.

On 23 November 2012 09:25, Chris Ford notifications@github.com wrote:

The current spec seems to assume that the facilities URLs are on the same host as the collection, which limits the ability of people to create their own (standard-compliant) collections.

The spec says that the list of facilities must be made available at a url like so:

http://example.org/facilities

and individual facilities like so:

http://example.org/facilities/123http://example.org/facilities/456

Let's imagine that both Rwanda and Uganda have facilities registries, which is a possibility. So we end up with facilities that look like this:

http://rwanda.example.org/facilities/123http://rwanda.example.org/facilities/456http://rwanda.example.org/facilities/789 http://uganda.example.org/facilities/123http://uganda.example.org/facilities/456

Let's say that I'm running a study or project that involves some facilities from Rwanda and some from Uganda. I want to expose lists of those facilities I'm working with, and others who might join in:

http://malaria-study.example.org/participantshttp://malaria-study.example.org/candidates

These collections return facilities XML that looks something like this:

http://rwanda.example.org/facilities/456 http://uganda.example.org/facilities/456

Except, they can't do that and be conformant with the FRED API as we're locking down the URLs that collections and facilities have to be available at. In fact, if the Ugandan government wanted to make another list that linked to a subset of their own facilities, they couldn't do it and be sure that compliant consumers of the API would understand.

There is a tradeoff between how much structure we want to enforce in the URLs. The more structured we make it, the easier it is to document and talk about, but the less flexible it is. My bias is towards standardising formats and away from standardising URLs.

I think this is a less important point than the discussion over versioning though.

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

[ctford]

So if an organisation produced URLs like this, they would be conformant?

http://example.org.ci/installations-medicales/123

I agree it would be a good idea to call out specifically what's an example and what's not, because a misunderstanding could see consumers of the API relying on URL details that may change.

[bobjolliffe]

On 23 November 2012 12:03, Chris Ford notifications@github.com wrote:

So if an organisation produced URLs like this, they would be conformant?

http://example.org.ci/installations-medicales/123

According to what is currently written, yes. Though Justin is at work formalizing this so we need to watch carefully what he writes :-)

I agree it would be a good idea to call out specifically what's an example and what's not, because a misunderstanding could see consumers of the API relying on URL details that may change.

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

[rowenaluk]

this sounds like it was just a point of confusion. conclusion: URL structure is not part of the specification. we only state that a url must exist which points to the api resource of a facility, but we leave the url structure up to the implementer.

if anyone disgrees with this, feel free to reopen this issue.