A review of all most common API editors
by @orliesaurus API enthusiast
🔥 You should totally read my “one year later” update blog post
Which API editor to use?
Looking at integrating API docs in your website?
Want to quickly lay down a few endpoints and render documentation in a click?
Look no further, here’s a good breakdown of some of the best editors you can find publicly on the net. You can use them to build, document, expose endpoints and make your API become an interactive playground for developers.
I reviewed the most common API editors below, if you’re new to the API world you’ll find the below quite eye opening and will help you make the right choice when deciding who to host your API documentation with.
Please do add comments if you feel I missed something and I’ll update/correct
SWAGGER
by Swagger.io (YAML/JSON)
First Impression: This looks like MuleSoft’s API Designer after a facelift
API Modelling Flexibility: ★★★★★
TTL (Time to Live): ★☆☆☆☆
User friendliness: ★★★☆☆
Introduction
Swagger is the most famous editor that uses a markup language similar to RAML as the basis for the specification of the API logic. In fact the language, called YAML was the basis of the RAML spec. However you need to host it yourself on your own server.
If YAML sounds bad to your ears, as an alternative option Swagger has full support for specs written in JSON.
Both options are supported, that’s something that I find pretty cool, but which one is the easiest to write and learn?
The RAML spec is quite simple to figure out but takes some time to remember all the rules. Luckily YAML and RAML share a pretty simple syntax that requires just a logical approach and some time to get accustomed to it.
Unfortunately unlike the API editor/modeller provided by MuleSoft, you don’t actually get in-line error highlighting on the side of the editor (line number) it’s a real shame.
But Swagger has more than just an editor, because as you can see from the screenshot, there is a whole consume mechanism built in the documentation that will allow you to consume the API from the external documentation viewer, built by the same team behind Swagger itself.
Besides the look of the tool, which reminds me of the early years of the new millennium, the swagger documentation viewer is pretty powerful. It supports different types of authentication, endpoint resource grouping, a quick way to edit the schema of the payload and an easy way to display and alter query parameter (when required).
There is no code generated visible, yet from their website there is a reference to an addon to produce SDK from one’s API with ease.
Conclusions
• User friendliness — RAML and YAML are very similar, it takes a bit of time to get used to writing APIs specs in the language but unlike other editors reviewed above, it is not really user friendly to the developer. This product and the Mulesoft one do pretty much the same thing. Sure there are a few differences, especially in the debugging section but the remarks on their user friendliness go both way. It will take some time to get used to write perfect RAML/YAML “code”.
• Flexibility — The spec is really well defined and covers the majority of the use-cases in modern’s RESTful APIs. An API designer or architect will find a lot of guidance in the Swagger community repository on GitHub along with a very large amount of information to create REST compliant designs. Unlike MuleSoft’s product, which is the most closely comparable product to Swagger, the swagger documentation explorer (SWAGGER-UI) can be integrated painlessly in pretty much anything rather than having it as a portal of its own. Extra points for being open-source software.
• TTL(Time To Learn) — 4h — Sadly it takes time to learn how to use R/Y-AML. Spending a few hours actively trying to get your API to render is just needed. Thankfully once you get the handle of the markup language it gets faster.
Mashape API Editor
by Mashape.com
First Impression: Is this a fairy tale? Mashing buttons left and right.
API Modelling Flexibility: ★★★★☆
TTL (Time To Live): ★★★★☆
User friendliness: ★★★★☆
Introduction
When using the Mashape API editor you immediately see that you’re going to be able to generate code snippets in your favourite language to consume APIs on the fly. Unlike other editors, there is no language spec to follow. Instead a process of clicking boxes to add endpoints, parameters and models to craft your API takes place.
The power of this editor is in its simplicity, you’re not going to read a manual to use it.
On the other hand there is no real user on-boarding and for example, setting up the base URL of your API is done under the ”Analytics & Settings” page rather than on the same page where you document the API.
Luckily there is clear documentation on how to add an API to Mashape by just following a few screenshots and steps anyone can become an API master of the platform.
The editor comes with out of the box support for a tons of features including customer support (API Support (1) in the screen below) and the ability to add billing and thus monetising it in seconds.
Unlike Readme.io Mashape supports a ton of different authorization mechanisms: OAuth 1 and 2, Basic Auth, Query parameters, Header authentication.
Mashape is a great tool for APIs with a small amount of endpoints that want to promote their API through the market place, or embed the documentation on their own site.
Conclusions
• User friendliness — It’s very intuitive to use, however as an API architect when adding a lot of endpoints you’re in for a bit of a struggle. The editor becomes stuffed with information, and the repetitiveness of adding endpoints can become frustrating. On the other hand if you’re a consumer the documentation explorer is actually really easy to use and produces nice code snippets that can be copied and downloaded to your desktop.
• Flexibility — Mashape’s API editor is a very flexible product that allows anyone to add APIs. Not only it supports headers, querystring and multiple payload types; it makes it a breeze to add to its marketplace without the requirement of having learned a book of API jargon and keywords.
• TTL(Time To Live) — Under 1 hour. It’s really straight forward, you can’t go wrong with this editor as it really simplifies the adding of an API to the bone. There’s not really anything that is required to be read. So you can forget the spec documentation, and dive in adding endpoints, models and go live in seconds.
API Designer Studio
by Mulesoft (RAML)
First impression: Clean bootstrap interface with a console interface.
API Modelling Flexibility: ★★★★★
User friendliness: ★★☆☆☆
TTL (Time spent before going live): ★☆☆☆☆
Introduction
After signing up to the service we are presented with the choice of building an API with the RAML based API-designer by Mulesoft.
The API editor is a web app built on top of the RAML specification, which is a way to write API’s architecture. RAML is understandable to humans while at the same time being also machine readable. The standard has been backed by some of the most knowledgeable people in the industry and is therefore very solid when it comes to being able to represent APIs in text, furthermore to the seasoned developer RAML quite easy to understand.
From a verbosity perspective, RAML it’s concise. You only write what you need to define, leaving little space for creativity.
Thus, the editor isn’t anything impressive, you’d be better off with your favourite text editor with a RAML plugin, for example here’s one for Sublime. It supports multiple tabs and files editing at once. We’re in 2014 after all
The editor is as good as a terminal with a drawback. This is something I find quite annoying in fact: you’re only shown one RAML error at onetime. Having to correct an error, save, correct can tend to be tedious when working with different files
Once you’ve created your API specification you are required to add it to something called an API portal. There you can expose your newly created API to the world, adding explanation for readers where it’s needed.
Conclusions
• User Friendliness — Novice users won’t be greeted with any welcome tutorial on how to get started with the API designer, onboarding is non-existent. There are many references pointing users to go and study the RAML standard but that’s pretty much it.
• Flexibility — Thanks to RAML the editor is very solid and supports entirely the markup language to define anything within your RESTful API. Endpoints and architecture are safe, not much can beat this flexibility
• Time to Live (TTL) — Approx 3h. Without spending a few hours actively toying around with RAML you won’t get very far. Depending on your ability to understand the REST architecture and the specification, how to use each block appropriately to represent your API, you might need more or less time.
README Editor
by README.IO
First impression: Hip Product for the Small Flexible Startup
API Modelling Flexibility: ★★☆☆☆
TTL (Time To Live): ★★★★★
User friendliness: ★★★★☆
Introduction
Readme.io is a tool to create READMEs of all kinds, whether you want to create F.A.Q.s or RESTful API documentation, you’re on board. Obviously the latter is what we’re most interested in.
So I decided to give it a go, signup and build the library API that I have built in RAML above. Additionally I could have just imported documents as Readme.IO supports APIDOCJS spec.
The first thing that jumped to the eye from trying to build the documentation with this editor is that, unlike the previous, the user is left in total control over how it will document its API.
After defining the endpoint, the authentication(at the time of writing this post it seems to only support basic authentication) and the parameter(s) that can be passed to the endpoint the user is given a the ability to post the expected/default API response.
Additionally to this you can add extra bits and bobs, including tables, images and inline html.
The design is very flexible and it allows you to create and maintain a list of endpoints and respective http methods and group them in total freedom.
All in all this is really a documentation tool. Just not focussed on APIs. There are a few things missing here, especially in the live api tester
I do understand that SaaS is about making a tool that is awesome at solving a specific or an array of problems.
I believe the state this project is currently standing at is too premature, but clearly with the early traction this tool has been seeing it lays a solid base for building of a promising editor.
Today Readme.IO looks polished from a visual perspective, but also incorporates the typical startup aura (subtle little jokes in the UI) that make the experience nothing less than pleasant and make me want to come back for more!
Conclusions
• User friendliness — You can just intuitively take this tool for a spin and you’ll end up with something that makes sense. I’ve only given it 4 stars because I believe there’s an issue with the URL parameter that I can’t seem to get working no matter what I do.
• Flexibility — Yes it’s a flexible product, you could write and explain how to make cookies with this tool, it’s that flexible. Sometimes however I feel this tool is still too beta-ish. I believe some core features are still missing and others are needing some polishing.
• TTL(Time To Live) — Under 1h It’s really straight forward and it has a good user onboarding flow. Nothing to learn besides the ability of moving your mouse and hitting keys on your keyboard.
Apiary API Editor
by Apiary (API BLUEPRINT)
First Impression: This looks as the next iteration of MuleSoft’s API Designer
TTL (Time to Live): ★☆☆☆☆
User friendliness: ★★★★★
Flexibility: ★★★★★
Introduction
Similarly to the first editor I reviewed this one is basically a fully fledged a text editor box in the middle of the browser. The errors appear inline and are really well described, so you know what you need to do immediately without having to refer back to the docs.
Using API Blueprint is maybe even more awesome than using RAML. Its clever way of leveraging the power of markdown to create a specification that can be followed to easily document in a tidy manner an API is outstanding.
The only visible downside? Slightly more verbose in terms of keystrokes than RAML, but maybe that comes with a higher degree of human/ beginner friendliness.
The documentation view provides the reader with a well portrayed clean and minimalistic view of an API’s endpoints, request parameters, responses as well as auto-generated code to copy paste into apps to execute requests which will match the ones generated in the browser. This way it is possible to quickly run API calls, identify the objects responses and integrate the calls into an app in seconds.
Interestingly each endpoint has a comment section where users can leave messages to eventually collaborate. Not sure about this feature, it feels like hard to use or keep track of messages without an aggregated view.
Conclusion
• User friendliness — The interface is slick, the features are there and simply one click away, precisely placed where you would expect them to be. User experience wise, this is as good as it gets, you know what you’re expecting by the minute you land on the homepage to the minute where you publish your documentation to your developer crew.
• Flexibility — Because the way you add resources is by using a language (APIBlueprint) you have maximum flexibility on how your endpoints are rendered. And although the editor is just a text-editor, in return you get a really nice interactive documentation browser for your API consumers to run queries against your API and generate code snippets.
• TTL(Time To Learn) — 2 hours. You need to learn a whole new “language” to describe your API, just like RAML. Technically because it’s markdown and if you’re a coder this might be a little faster for you to learn.
Conclusion
All the editors have their pros and cons, if you’re a highly technical user you’re possibly very comfortable with the speedy nature of Swagger or API Designer.
If you’re looking for a different approach and a clean hip design, you should probably try API Blueprint and its editor.
Finally if you’re a company whose product is an API and wants to quickly appeal developers you should point to Mashape.
Or give ReadMe.IO a go for a lightweight editor for very simple APIs
There is no real winner because it depends on your requirements.
Looking for flexibility over design or design over flexibility or… ease of use over everything, then you’re better of getting accustomed with one or another tool and stick to it. The API Market is upcoming and rising day after day, IBM and SAP just announced their own solutions..watch this space!
Thanks for reading this far, you’re awesome! Get in touch or..
