Hacker News was recently home to an active debate on the best way to write an API specification. The community weighed in with the latest information on API languages including API Blueprint, RAML, Swagger, as well as the API tools including Apiary, apiDoc, Readme.io, Slate and many other options.
Christopher Shroba, a student at the University of Illinois at Urbana-Champaign, kicked off the discussion by asking, “What’s the best way to write an API Spec? I’m working on a project that contains a REST API, and I want to write out a spec before I start. Are there tools for this, or should I just make a Google Docs table for it or something?”
For many people, the first option is to manually organize the information in a table. This is quick, but leads to problems with accuracy and version control for the API and documentation in the future. Most people in the discussion felt that developers are better off using tools built specifically for API development.
API specifications maintained in separate files
As Pete Gamache summed up, “there have been an explosion of API specification formats in the last few years. No clear winner has emerged.” With API development technology changing so rapidly, people new to APIs are faced with a wide set of options.
Swagger
Rod Waldhoff of Intellinote responded first with information on Swagger, Swagger UI, and his project, Swagger-DSL. Other people chimed in with more information on the Swagger ecosystem. For example, Grape-Swagger enables developers to use Swagger with Grape, the REST-like API micro-framework popular with Ruby developers. Another project, Swagger Codegen is used by people preferring to write Swagger specs in YAML and then translating them to JSON, thus blurring the lines between markup formats.
Last summer, InfoQ covered Tony Tam’s announcement at GlueCon of the Swagger 2.0 Working Group and an online code editor for dynamic YAML to Swagger UI conversion. According to Tony, Swagger had 10,000 production deployments at that time. There’s definitely active development, a substantial base of users, and buzz around Swagger, but it’s far from a de facto standard. Last September, the Swagger 2.0 specification was released and project members are still working on upgrading their code generation tool chain.
RAML
John Sheehan, co-founder of Runscope, brought up RAML, a RESTful API Modeling Language. Mark Wilbur felt that, “The best tool is probably RAML. It's very succinct, looks like YAML and has powerful features such as traits that really simplify the process of documenting many endpoints with similar traits (e.g. pagination).”
Erwin Andreasen, CTO at Decipher, wasn’t as enthusiastic. “I tried RAML -- it makes sense for quick prototyping of your resources and methods, but I couldn't see myself writing too much documentation as a giant nested YAML document.”
API Blueprint
Pete Gamache introduced us to API Blueprint, sponsored by Apiary, “another emerging format for API description. It’s written in Markdown, so it is very human-readable and writeable. It is not yet suitable for hypermedia APIs. Like JSON schema, it’s tooling includes validators, client library generators, mock server generators, docs generators, etc… API Blueprint is a nice format to write in a text editor and is easily read as-is or rendered from Markdown; no separate docs generator is necessary”.
Muad Dirac wrote that “API Blueprint allows you to describe your API responses with JSON Schema. They sit at different levels - Blueprint for specifying URLs resources are accessed with, and JSON Schema for validating the payload.”
Slate
Slate was recommended by several people. Simi of Lavaboom contributed this: “We tried a lot of options at Lavaboom (including Apiary, Readme.io, Swagger, etc) and ended up using Slate. Slate struck a good balance between (1) syntax (2) ease of use and (3) good looks, although I wouldn't call it perfect in any of those departments.”
Pete Gamache added, “Slate is an API documentation framework/template, designed to generate very handsome documentation pages. Its concern is more documentation than specification, and therefore doesn't concern itself with things like library or mock generation.”
API specifications generated from inline comments
The benefits of having APIs pulled from inline comments were also discussed by participants.
apiDoc
Gabriel Dillon, co-founder of ReadMe.io, uses apiDoc to help with inline documentation for RESTful APIs. The project website describes the functionality: “apiDoc creates documentation from API annotations in your source code.” It can be used with any Javadoc capable language, including C#, Go, Dart, Java, JavaScript, PHP, TypeScript. Other languages are supported with multiline comment code.
Liamcode also liked apiDoc and inline comments due to the integration with his version control system. “You define the API in comments within your code. When you run apiDoc it scans your code and generates pretty documentation. I tried various other solutions before this such as Apiary. apiDoc is really easy to update as it is part of your code, which also means it goes into your version control!”
Andrew Stuart feels it’s better to have the documentation and API spec in a separate file. “Regardless of solution chosen, Swagger or otherwise, I'm puzzled as to why people integrate the API spec/documentation into their source code. Seems to me to provide incredible scope for bugs and dramatically increase software complexity.”
Erwin touches on the negative impact on code readability of having much longer documentation than code. “I also tried apiDoc which might make sense of you have internal documentation you want to quickly expose. However my docs are longer than the code implementing them, so I don't like mixing them in as e.g. apiDoc would require.”
API-first versus code-first development workflows
Developers are still caught up in a debate as to whether it is better to start off with crafting the API specification or with writing source code for the API implementation.
Kikibobo69 said that from his experience, “an API-first approach seems to lead to higher quality APIs compared to just hacking something together and annotating it to extract docs. Also, having a really nice client without a complicated compile-time dependency graph (on the JVM) feels like a sweet spot.” z3t4 had the exact reverse opinion: “I always start ‘backwards’ by writing some example code.”
The discussion’s last comment advocates for modelling REST resources: “Why not model your REST resources so that API documentation can be auto-generated from your actual code? Makes a lot more sense to me than trying to generate code from documentation.”
Contrasting SOAP and web API approaches
Jestar Jokin drew a parallel to the experiences enterprises had with SOAP web services and the bottom-up experiences in the web API field. He also summed up the challenges API developers face with fragmentation of the technologies.
“Isn't this why enterprises favoured things like SOAP web services with XSDs and WSDLs? The verbosity acts as human and machine-readable documentation, and the files can be used to generate client code. Ignoring the benefits of using HTTP as the request transport mechanism, this seems like another cycle of people coming up with a comprehensive but complex solution, other people getting frustrated with the complexity and developing a simpler solution, then filling in the gaps (such as documentation) until the solution is a complex patchwork of competing libraries, none clearly better than the others, leading to fragmentation of mindshare and expertise…”
Community help needed to define best practices
The highlights of the discussion in this article give a feel for the diversity of choices in this space. Tools used to write API specifications are still in a nascent state. Some technologies work well in certain areas such as human readability, but lack features in other areas.
Developers, as a loose community, need to continue to test technologies, share experiences with others and define best practices. Feel free to list your opinion in the comment section about the best way to specify APIs.
Disclaimer: the author of this article works for Restlet, a web API platform provider, and participated at the end of the debate covered in this article, mentioning the Restlet Studio tool.