Some work has already been done on an API Convention/Standard:
Aside from linking to those here, have we any thoughts on how best to surface these documents, and the WG in general? Dare I suggest api.iatistandard.org … ?!
I think we need to try and consolidate the documentation into a single source when all is decided on.
I’ve been checking out Swagger which looks really good from my point of view; however if we wanted to adopt this, we’d need to make sure that all API builders would utilise the same patterns of coding (and used Swagger) - and then we have the question, which do we point to as “The IATI API Documentation”?
I think the docs should cover 3 areas:
- How to build an API for IATI Data
- How to use an API for IATI Data
- What APIs are there already existing (and what do they provide)
Maybe the how to use is covered individually within each of the implementations though…
We’ve implemented Swagger for our latest API in Akvo RSR - we really like the generated info, especially as this reuses the help information we have in place in the code already. http://rsr.akvo.org/rest/docs/
The one thing we’ve yet to add is the information about how to actually implement, for example with RSR users need to send or receive tables in specific orders so that they can access the full set of relevant information, and this is something additional we need to provide.
But for the basics, this has been great - and devs (and almost devs like me) can instantly get at lots of useful info.