URL updates and root API behaviour

[ydagenais]

• singularized api base URI
• using dogs collection instead of dataset for examples
• defined default behaviour of root /api/

[nschonni]

API isn't an entity, so I don't think it should be pluralized. I've never come across "apis" as an endpoint, unless it is a API marketplace.

[ydagenais]

I agree it does look a little odd. You may or may not have noticed that there were already some /apis/ as examples throughout the document; I was making it consistent. Regardless, I'm glad it's generating discussion.

The thought was yes, to make it a hub. Most departments I've talked to have or are planning multiple APIs. But perhaps that should be a separate item such as a vanity URL of /apis (like /developer) or simply just have the /developer.

e.g.: http://developer.linkedin.com/apis and http://api.linkedin.com

As a side note, it's interesting that http://api.linkedin.com generates a 404 and the page itself isn't relevant i.e. should have offered to or automatically redirected me to their developer portal.

We wanted to avoid having /api and /apis to describe both the inteface to and the collection of APIs.

@chrismajewski thoughts?

[nschonni]

The LinkedIn example with "apis" is documentation only, and list several APIs that are exposed as pluralized entities under api.linkedin.com/*

[chrismajewski]

The pluralization has precedent and be it an api or documentation the logic is sound:

google.com/apis/ developers.facebook.com/docs/reference/apis/

Most example are a single "API", the need to pluralize it is moot and why the majority of our examples will be /api/. In this case, however, we are trying to account for organizations having more than one and we've realized recently that even the definition of API and Endpoint is murky.

I could call what linked-in is doing one or multiple apis. They've chosen to describe them as multiples in the documentation but treat them as a single unit by burying them in a single version. /v1/people instead of /people/v1

Better execution has a distinct URI for each such as:

maps.googleapis.com/maps/api/staticmap?... graph.facebook.com/act_{account_id}/users/123456?access_token=__

That doesn't work for our organization, we are simply not structured in such a way to make that work. Likely direction will be to consolidate the APIs as we do HTML, I'd much prefer pluralizing the lot when there may be hundreds.

canada.ca/apis is more descriptive in that case than canada.ca/api

More shocking should be the use of API in a french context instead of IPA.

[nschonni]

google.com/apis/

Doesn't exist, forwards to code.google.com

canada.ca/apis is more descriptive in that case than canada.ca/api

api.canada.ca would be more appropriate for the actual endpoint.

---

All the pluralization examples given are for documentation hubs and not API endpoints. GitHub is another example where the docs live off the developer subdomain, but all API endpoints are off api http://developer.github.com/v3/

[chrismajewski]

Ok, it was google.com/apis/, let me replace that with the leading directory for APIs:

http://www.programmableweb.com/apis/directory/1?company=Yahoo

The point is there is no clear standard and the term API is becoming a noun. When you have two or more pluralizing it is/was an established practice of API leaders in the field. Some continue to use the singular. At this point it's a choice of preference and I personally prefer to use proper and descriptive grammar.

And I agree, I'd love api.department/apiname but we can ask a development staff to add a directory or level to their CMS path but you can't require a DNS entry. It's not permitted by most departmental level IT policies and adds to the confusion we are trying to solve with consolidation.

We still have to write something that's implementable till consolidation.

I'll review the structure to include a step further.

[chrismajewski]

For anyone else listening in this is a good time to comment. We are in the open soliciting comment.

[nschonni]

The other reason why these major sites use a subdomain is that an API should be a cookieless domain.

http://www.programmableweb.com/apis/directory/1?company=Yahoo

Intresting link, but that is a directory of APIs as discussed above https://github.com/wet-boew/wet-boew-api-standards/pull/23#issuecomment-31181289. Looking at http://developer.yahoo.com/everything.html, the actual Yahoo APIs are singluar like SERVICE.yahooapis.com/VERSION/

[chrismajewski]

Finding more examples of /apis/ in the URI is pointless. They are both in use and acceptable, my first example of google.com/apis/ presently redirected or not was sufficient. If you can't see or accept that your working to satisfy a belief.

I will move forward with the premise that they are both acceptable and work towards a recommendation. It may be singular to be consistent with subdomains but it may be plural to be grammatically or logically accurate.

Common practice for api. and developer. subdomains seems to be singular. It can't be a requirement but it may be an exception to or simply a best practice. I know EC is working towards it.

[nschonni]

Finding more examples of /apis/ in the URI is pointless. They are both in use and acceptable, my first example of google.com/apis/ presently redirected or not was sufficient. If you can't see or accept that your working to satisfy a belief.

My point was that none of the examples given or that I've found use plural for anything but documenation sites (like the suggested example.gc.ca/developer/ or developer.example.gc.ca content).

It can't be a requirement but it may be an exception to or simply a best practice. I know EC is working towards it.

Why can't that be a requirement? There is plenty of president on mandating URL structures in the GC.

[chrismajewski]

API or documentation it makes no difference, the logic is the same. It's a central location for /apis/ with the acknowledgement that we may have more than one. If I say /api/ I'm implying there's only one which may not be the case. It's a good recommendation that deserves more than a circular argument.

Consistency with subdomain use is a good argument for a singular /api/ if you wish to continue but you need to acknowledge the validity of Yves' proposal. I will give it due respect.

As for mandating subdomains, as previously stated, departmental IT policy will not always allow it. I'm presently reworking the earthquakes API. NRCan will not allow api.earthquakescanada.nrcan.gc.ca without a hard standard, that hard standard is a long way away and people are developing today.

It this first round of standardization I'm following the well through out American lead in being minimalist. Mandate your interoperability needs and little more to get people on-board. If you require too much or things that are not possible you make the standard impossible and people will ignore it.

No use having the prefect law no-one follows.

[nschonni]

It this first round of standardization I'm following the well through out American lead in being minimalist.

https://github.com/WhiteHouse/api-standards#good-url-examples

[chrismajewski]

I'm well aware of that document, that's the document we started from. It was insufficient for our needs so we rewrote it. In fact their document isn't even a standard, it's a series of best practices loosely researched.

You seem to be, however, missing the point of what you quote. I'm not talking about /api/, I'm talking about providing minimum requirements that are implementable today. Today anyone can add '/api/' or '/apis/' but they can't add 'api.department/api-name'. This is why only the URL insert is requested.

I'm sorry if I upset you but I'm done going in circles. I'll leave this open for new arguments and revisit this to a conclusion some time next week.

[ydagenais]

The problem with most /api/ examples is that they are followed by a versioning of the entire API. e.g: /api/v1/. I know versioning is an entirely different subject but I wanted to point that out.

As for /api/ vs /apis/, one of the goals for URLs is to make them intuitive for users (developers) to also discover APIs on any gc.ca website. e.g: Simply go to example.gc.ca/en/api/ or example.gc.ca/en/developer to see what example.gc.ca has to offer as APIs.

I agree that industry has adopted either /api/ for singular interfaces or a host (or folder) name that is specific to the API e.g: https://maps.googleapis.com/maps/api/. Hey, look! an "s". :)

I consider linkedin.com as an example of an API to a single service. Yes, they do offer access to a series of collections (people, groups, etc) but it's all accessing the same service.

@nschonni as you pointed out, examples of /apis/ refer to information on the available api(s); we equally want that user experience. Does this mean we'd end up with three URLs related to APIs?

1. /api/ the actual machine interface
2. /apis/ an information landing page for the available APIs
3. /developer/ same as above or a variant of some sort?

Also, I agree with @chrismajewski that requiring APIs to be defined at host level would be challenging.

[chrismajewski]

Hurg. /api/ and /apis/, your both killing me. ;)

Would not both be, technically, pointing to a repository of APIs? Even if just one.

Or does, brace yourself, the /apis/ directory have to be a api of a collection of apis?

[nschonni]

@ydagenais :+1: I think the existing section on the developer https://github.com/wet-boew/wet-boew-api-standards#312- developer covers the documentation segregation well already.

---

I don't think example.gc.ca/en/api/ with the language in the URL is the best approach/recommendation.

---

I'm sorry if I upset you but I'm done going in circles.

I wasn't upset, I just forgot to use emojiis :wink:

---

The problem with most /api/ examples is that they are followed by a versioning of the entire API. e.g: /api/v1/. I know versioning is an entirely different subject but I wanted to point that out.

:+1: very important point. Maybe example.gc.ca/api/SERVICE/v1 if a unified API like GitHub/Twitter isn't used.

[ydagenais]

Who knew an "s" could stir up so much conversation!

This document is a challenge because it needs to be a one-size-fits-all. text/html is a valid response type therefore, http://example.gc.ca/en/api/weather/alerts would need to return a valid HTML document in the language requested if a user accesses this URL with their browser. Via machine code, you could force it otherwise with the Accept-Language. That's just one edge case. The way language is defined in the URL varies too much right now with each department. Yes, the examples do it one way but I don't think the document states that language is to be done a specific way other than to respect the user's selection via URL or Accept-Language header. The language logic deserves its own ticket therefore I'll stop there on that topic.

Back to the matter at hand. What would be the expected behaviour if a user goes to example.gc.ca/en/api (without specifying an actual API)

1. 404?
2. redirect to /developer?
3. list available API(s)?
4. other?

The intent of /apis/ was to serve up an index of available APIs. Does it still make sense to do this if we use /api/?

[ydagenais]

The following APIs return 404s when accessing the root:

• https://api.linkedin.com
• https://maps.googleapis.com/
• https://api.twitter.com

Facebook improved on this a bit. http://graph.facebook.com returns a 400 with a JSON error:

{

    "error": {
        "message": "Unsupported get request.",
        "type": "GraphMethodException",
        "code": 100
    }

}

Microsoft offers something more helpful. http://dev.virtualearth.net (Microsoft Bing Maps) returns a 302 and redirects to their API documentation.

NHTSA API http://www.nhtsa.gov/webapi/api returns a 302 and redirects to their API documentation.

HealthData.gov http://hub.healthdata.gov/api returns a 200 and JSON indicating the API version.

The NHTSA API offers the best solution (but with a 200 code) for both UX and SEO/crawlability of the data as the landing page could also serve as a starting point for crawlers if desired.

As a conclusion, I recommend that /api/ be used and drop the /apis/ even if /api/ contains a collection of APIs. This seems to be the most adopted and thus intuitive format for users. Finally, API documentation will remain as recommended under /developer/. In the event a user navigates to the URL of say http://example.gc.ca/en/api, the recommendation will be to return a 200 and a useful landing page (or requested media type if available) listing available APIs and a link to their respective documentation.

I will update my pull request to only include my other changes and @chrismajewski I recommend you accept @nschonni 's pull request to remove the "s" on the examples.

If we have more thoughts on the topic, then I suggest we open up a ticket to discuss further.

Cheers, Yves