API Design Guide

[kyyberi]

This is a topic that came up in Dev Day meeting in Estonia.
This might be a good starting point https://github.com/18f/api-standards

[andreskytt]

Looks good enough. Should we have something to add, it should be contributed to 18f (if they are welcoming to this sort of thing) rather than building our own version.

[kyyberi]

+1

[kyyberi]

I would extend or at least link posts with more information to some parts. For example error handling is rather vague and could contain a little more.

[veikkoeeva]

I'll make a quick jump here and wonder if the API design guide should be aligned with that recommended by the European Union? I mean recommendations such as The EU Open Data Portal (example).

Taking a glance at the 18f standards, I think I for one would prefer the style GitHub uses, for example, or following the Europeans recommendations. About error handling and interoperability, there was recently a nice presentation in NDC Oslo: Crafting Evolvable Web API Representations by Darrel Miller.

[kyyberi]

I can't find any kind of EU driven API guide line doc so hard to say. 18f is suggested so that we don't need to start from scratch. If it needs fine tuning to comply with undefined (?) EU practices, then fine let's do that.

[veikkoeeva]

@kyyberi Ah, my apologies for the omission and lack of reasoning. I meant something like 10 Rules for Persistent URIs. There's a lot of information on linked data (e.g. JSON-LD) too, but the linked pdf report has plenty of good points on restful linking too.

With regards to my specific comment earlier on embedding version numbers to URLs (I wonder where I got that, hmm):

4.2.2 Avoid version numbers

Although  concept  schemes,  ontologies,  taxonomies  and  vocabularies  are  likely  to  go  through 
iterative cycles of change, version numbers and status information should not be included in the 
URIs. Rather,  the URIs should remain stable between versions and new  ones  minted for new 
terms.  URIs  may  be  deprecated  and  their  use  discouraged  but  they  should  nevertheless  be 
maintained both in terms of the actual URI and the resource they identify. 

I appreciate you have taken the time to make this topic public. I'm a bit concerned about using, or contemplating on using, a guideline that is likely driven by legislation, needs and motives partially different than here. Looking at the 18f page it is itself very thin on API design and then glosses over some technicalities like using SNI, CORS, perfect forward secrecy etc. (not even enumerating exhaustively the issues) that are not part of API design. It's not really possible to go into production without doing that, I think (either the API wouldn't work at all, the security review would halt deployment or the API would pawned in no time).

In the same time, I have to tell I haven't read any of these guidelines throughly so as to being able to compare them in detail, but it looks like it's not possible to just fine tune one to another (maybe I interpret this too literally) and that the EU guidelines provide the same thing and provides guidance on adding national data sets for public consumption on EU level.

It looks like the EU guidelines are more aligned with linked data, I'm not sure about the motives (history) of 18f. It looks like being a catalogue of APIs, which we should do, definitely (Swagger?) and using some technologies (Solr/Lucene etc., sure, of course) and maybe a bit about AAA (should we go to something like OpenID Connect/OAuth 2.0? on public Internet).

[kyyberi]

Kiitos kommenteista ja isosta määrästä informaatiota! Syksyllä hankitaan (VM rahoituksella) community manager X-Road yhteisölle ainakin 6 kuukaudeksi (toivottavasti myös jatkoa) ja hänen yksi tehtävä on koostaa API Design Guide yhdessä yhteisön kanssa. Tervetuloa mukaan viimeistään silloin kontribuoimalla lisää.

Thanks for the contribution! We are hiring (prolly around 9/2015) community manager for Finnish X-Road community and one of the his/her tasks is to construct API Desig Guide together with the community. You are more than welcome to contribute more to that process.