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.
Community comments
Giant nested YAML document
by David Dossot,
Rest by examples
by Pascal Jaillon,
Re: Rest by examples
by Jerome Louvel,
Chorus.js
by Jean-Jacques Dubray,
Re: Chorus.js
by Erik Gollot,
Re: Chorus.js
by Jean-Jacques Dubray,
Giant nested YAML document
by David Dossot,
Your message is awaiting moderation. Thank you for participating in the discussion.
Erwin's very valid concern about "writing too much documentation as a giant nested YAML document" is mitigated in RAML via the usage of traits and resource types. Properly using these two constructs allows reducing drastically the amount of declaration needed for each resource/method.
Rest by examples
by Pascal Jaillon,
Your message is awaiting moderation. Thank you for participating in the discussion.
Exactly the issue we faced when developing rest2mobile: too many specs and no clear winner. Since we are offering a solution to consume REST APIs, we couldn't afford to rely on just one standard. We went with REST Request/Response samples instead: developers.magnet.com/
Chorus.js
by Jean-Jacques Dubray,
Your message is awaiting moderation. Thank you for participating in the discussion.
I'd like to offer yet another format, as part of the Chorus.js project.
The main advantages of the Chorus.js model are that:
a) the message formats are derived from a "Common Information Model"
b) the common information model entities and apis (message formats) can be versioned independently of each other
This model solves a key flaw in Schema languages (XSD, JSON-schema, Swagger...). These schema languages can be used to capture the structure of a data model, they can also be used to create a set of message validation rules, but they cannot be used for both at the same time. Their dependency management has no isolation mechanisms that would control how a change in the data model propagates to specific message formats (without impacting existing formats for instance).
These languages also support "altering" the data entity definitions when used in a different types of message formats (e.g. Queries and Commands). In general develops end up making all data elements optional (defeating the purpose of a schema language) just to be able to reuse data entities in query and command messages.
Chorus.js solves both problems while providing a model that can be used in a Resource-Oriented way or in an Operation-Oriented way.
Chorus.js currently generates WSDLs and XSDs and I have started to work on generating swagger.
I wrote a post on it recently.
Re: Rest by examples
by Jerome Louvel,
Your message is awaiting moderation. Thank you for participating in the discussion.
Thanks for the feed-back, the REST-By-Example spec looks quite interesting:
github.com/magnetsystems/rest2mobile/wiki/Rest-...
Re: Chorus.js
by Erik Gollot,
Your message is awaiting moderation. Thank you for participating in the discussion.
Chorus.js is interesting. And it's strange for me that we're realizing that we need a higher level of abstraction (higher than code itself) to explain the api.Code sample is good also.
we do something similar using....oh ! UML.
UML really allow us to describe the api but moreover it help us to design first these api. We then generate the code like chorus does.
UML acts as a DSL and allows us to be more precise on the semantic. We can add sample code usage for a dedicated language/framework and then generate a html documentation.
Re: Chorus.js
by Jean-Jacques Dubray,
Your message is awaiting moderation. Thank you for participating in the discussion.
Is there a thing UML can't do?