Multiple interfaces to the same API

[chrismajewski]

David Sampson ( don't have his github account yet ) brings us a real world issue.

In split language URL architectures you may be lead to two distinct names to the same API interface.

Proper design is a single URI for a distinct resource, in perpetuity.

I'll let David explain, then we open for comment. We are chasing official comment about this issue.

[samperd]

I am looking for guidance on URL’s for API’s within GOC.

I have been exposed to different approaches between NRCAN (previously) and EC (Currently). Right now at EC we are using two seprate URL’s split by lang:

http://data.ec.gc.ca/api or http://donnees.ec.gc.ca/api (examples with no end points right now)

I would like to propose to harmonize to a single API end point and would like some discussion or feedback. For example: http://donnes-data.ec.gc.ca/api

This structure would also impact data repositories as well, which might make file storage and retrieval a challenge. A harmonized example might be: http://donnes-data.ec.gc.ca/data

Are there TBS best practices or existing guidelines?

With geogratis we burned language into the URL. http://geogratis.gc.ca/api/en/.

However, with the modern web you should be able to DETECT the user language.

Also, what are the current thoughts on URL aliasing and Canonical URL’s with GOC? We worked hard with GeoGratis to kill aliases and ensure a single canonical URL for Search Engine Optimization (SEO). If you use two seprate URL's would you default the english to be the canonical URL?

Any Thoughts?

[chrismajewski]

@dyomides @samperd

For the documentation section, I still have to hammer out, Cedric and I were leaning as such

For the api: example.gc.ca/ipa-api if organization located in Quebec and example.gc.ca/api-ipa if anywhere else in Canada

For the documentation: example.gc.ca/developpeur-developer if organization located in Quebec and example.gc.ca/developer-developpeur if anywhere else in Canada

If required, for uni-lingual URL structure:

For the api: example.gc.ca/api example.gc.ca/ipa

For the documentation: example.gc.ca/developer example.gc.ca/developpeur

David is a few steps in front of us in implementation.

Please comment, I'll add this to the greater conversation and in a week or so we'll close with with a comment in the standard. We'll need one for the documentation section if nothing else.

[dyomides]

If we reach consensus the examples in the standard should be updated to follow the chosen approach so that we are at least consistent throughout.

I doubt many will argue for multiple entry points into the same API so it might be a lopsided debate.

As for TBS guidelines or best practices the only thing I can think of is what can be found in Appendix B in the Standard on Web Usability which is specific to website addresses/domain names: http://www.tbs-sct.gc.ca/pol/doc-eng.aspx?id=24227&section=text#appB

[LaurentGoderre]

@samperd adding the language as part of the path is against the norm of REST.. The URL should describe a resource and therefore the language wouldn't belong there. That is why we recommend it as a querystring parameter

For example:

https://example.gc.ca/api/recalls/12354?lang=en

[LaurentGoderre]

Also, as per termium, API is appropriate to use in French. Therefore only the domain part would potentially be bilingual.

https://api.cra.gc.ca/taxes/2012/?lang=en
https://api.arc.gc.ca/taxes/2012/?lang=en
https://api.cra-arc.gc.ca/taxes/2012/?lang=en

[samperd]

I like where this conversation is going.

Since we covered API's (I like the idea of using just API as per termium), and developer sites.

The next two cases would be data-repositories (some depts may still have a need for flat file repos) and Catalogues (A growing number of depts have scientific catalogues that offer more than data.gc.ca has to offer at this time. How do people feel about:

• Catalogue end point: http://organization.gc.ca/cat
• Data file repository: http://organization.gc.ca/donnees-data

Concerning the catalogue, I was thinking the general "cat" to de-emphasize any particular technology solutions (eg "GeoNetwork") and de-emphasize any particular catalogue service protocol (eg CSW or Z39.50)

Concerning flat file repos I would also suggest a formal recomention to de-emphasize FTP in favour of file transfers via HTTP. In the event that an ftp end point is required (due to clear business requirements based on user centered design methodology and clear customer requirements) then the URL should be preficed with the protocol without change to the rest of the url.

• http://organization.gc.ca/donnees-data
• ftp://organization.gc.ca/donnees-data

Thoughts?

[LaurentGoderre]

I don't have much experience with those use case but it looks good to me.

[nschonni]

Does anyone actually have an example of a French only API? I was looking around http://www.data.gouv.fr/, but couldn't find anything (also note they still use "data"...).

[jvanulde]

Not sure if its material to the conversation or not but it may be worth mentioning the HTTP Accept-Language header. Although it shouldn't be relied on its own it does provide a protocol (HTTP) level way to specify preferred language based on a users locale. REST as pattern doesn't specify what a URI looks like. There are best practices, but REST isn't a standard - we can design our URI's based on the policy constraints that we have. Personally, I like to include the language explicit in the URI path and not in the querystring. For example for the GeoGratis API we have http://geogratis.gc.ca/api/{version}/en/ or http://geogratis.gc.ca/api/{version}/fr/. Dereferencing http://geogratis.gc.ca/api/ (no language) takes you to the splash page.

[chrismajewski]

@jvanulde The draft standard has been restructured to require headers for media-type and language but loosely recommends using a URI component without being specific on how you define language.

The URI structure is wildly different from department to department and we this isn't the document to try and standardize it.

[chrismajewski]

@nschonni Part of the discussion that's missing is that a URI may be language specific, it may diverge from the root starting from the root ( http://www.nrcan.gc.ca/home vs http://www.rncan.gc.ca/accueil ). If that's the URI path they may do the same with the API's endpoint.

There may also be valid technical reasons to ( bandwidth, design, logic ) to not include both in the same request.

So accounting for the possibility of a unilingual endpoint does this jive? This logic mimics how the web presently works, one language with the link to the next.

[nschonni]

I swear I'm not just arguing with you for fun :trollface:

Since it is a programming interface and not directly intended for human consumption, I think it should be language agnostic and canonical. That isn't to say the /developer/ or /developuer/ endpoint shouldn't be language specific, and maybe even showing examples on returning uni-lingual results.

[jvanulde]

To add to the discussion, in the GeoGratis API we provide the alternate language to the developer via a link.

JSON:

{
    "rel": "alternate",
    "method": "GET",
    "hreflang": "fr", 
    "href": "http://www.geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/?alt=json"
}

ATOM:

<link href="http://www.geogratis.gc.ca/api/fr/nrcan-rncan/ess-sst/?alt=xml" 
      rel="alternate" 
      hreflang="fr" 
      title="Français" />

[ydagenais]

That's awesome @jvanulde. As you've done, we included something similar in the metadata section of the response in the event the response is unilingual. See https://github.com/wet-boew/wet-boew-api-standards#133-official-languages

It's great to see support for a language agnostic URI for the API resource. It still requires more validation to measure its feasibility for other departments to implement this. Which is why at this point, we have not put a firm specification on how it should be handled; only recommendations.

It would be ideal for the API to serve minimalistic default responses. However, if we had a language agnostic API URI, we'd have to default to returning results in both English and French. This uses up more bandwidth and in some cases more computationally expensive.

[LaurentGoderre]

Using the language in the URL is technically incorrect because a URL needs to describe a resource and in our case a single resource can be represented in different language. API URLs are not the same as web URL.

I also agree that those URL should be language agnostic and canonical.

[chrismajewski]

@LaurentGoderre That is true. We ask for example.gc.ca/api ( no /ipa/ ) to skip past that but some CMS are configured to behave in unexpected manners and the shortest path to an API is through that existing webserver.

So the environment you have to account for are as such:

/lang/ root and numerical id followup

http://www.aadnc-aandc.gc.ca/eng/1100100010002/1100100010021

Language specific URLS

http://www.nrcan.gc.ca/media-room/news-release/2013/14106
http://www.rncan.gc.ca/salle-medias/communiques/2013/14107

@nschonni has also brought up use of api.canada.ca or api.example.gc.ca. Using a distinct API domain creates that clear distinction required to be language agnostic in the URL. It'd be independent of the webserver's URL structure.

[LaurentGoderre]

I don't think a CMS should be use in cases of API. The canonical language agnostic can be a virtual directory or reverse proxy.

Using the api subdomain just simplifies everything. You could have multiple API in it as such:

http://api.canada.ca/news http://api.canada.ca/recalls

[chrismajewski]

There are a handful of discussions going on here.

Multiple endpoints, url structure, api design and language.

I can't close this today.