How do we document an API standard?


(Steven Flower) #1

We’ve talked briefly about ways and means to document an API standard, whilst also being minded that we should collectively build something to discuss/test in this early stage.

I was pointed towards Swagger recently - to help document an API (but maybe not an API Standard), so just wanted to share on the list. I’m sure there are others that exist. One limitation I can envisage is that such tools document an API with a base URL - whereas an API standard documents common/agreed methods for API calls, etc.

I know @Adrian was also interested in looking at ways to document, and I’m pretty sure @bjwebb has thoughts.


(James Hughes) #2

This is true. I’ve personally had better success documenting APIs with RAML. We found that Swagger caused too many implementation details to bleed into the API that required too much work to fix. This is because Swagger originated in the Java world and was very tightly coupled to an annotation driven approach (which led to very annotation heavy endpoints). We also found that the most interesting stuff we would get form Swagger was contained within string based annotations which wouldn’t be automatically updated when your API changed (which negated the point of Swagger and its tight coupling with your code). I suspect this has improved in the last year or so but I haven’t really investigated.

So back to RAML. RAML allows you to write an API specification in the form of a YAML style document that can be applied to any base URL. It is also possible to generate API clients and (potentially) tests against this document. You also get the actual documentation that can be pointed to a test environment for live examples (similar to Swagger).

The big difference I found between the two was the Swagger is good for documenting existing APIs or evolving new ones as you go. RAML is much better suited to designing APIs and I think the tooling certainly echos that opinion.

However, yes, both tools are more aimed at documenting an API instance rather than standards but I do think RAML would be a much better fit fir at least defining a standard from a technical perspective.


(James Hughes) #3

It’s also worth noting that Swagger API’s can be exposed without having to annotate code just by crafting the Swagger JSON document but in comparison to RAMLs YAML DSL the Swagger JSON is more of an artefact of generation that something designed for humans to write (e.g. the RAML editor has dynamic validation and type hints for documents).