For all the time I’ve been working on Paw, I tried to stay updated with the new tools and services available to API developers, so I decided to publish some thoughts about the most mainstream ones, as well as a few that I think have big potential. This short overview will hopefully help you choose the right tools for your needs.
When building a web API, one’s first choice is the language and framework. But soon after, we come to realize that we need tools to test, describe and document our API.
Playgrounds and Debug Tools
As soon as you start writing some code, you’ll be tempted to try out your code. That's the hacker spirit!
HTTPie makes interaction with web APIs more human-friendly
If you’re the kind of guy that prefers command lines over GUIs, I can’t recommend more HTTPie, which aims “to make CLI interaction with web services as human-friendly as possible”. It has an easy to remember syntax that won’t make you feel nostalgic about cURL, and will definitely bring some color and joy to your Terminal!
Otherwise — and under the cover of a disclaimer as I’m the founder — Paw will help you visually play with your API, as being a graphical HTTP client. If you’re dealing with many endpoints you’d like to keep organized, run all your requests sequentially, deal with OAuth or generate code snippets for the consumers of your API, it will be your everyday buddy. We’ve also created Pawprint to quickly share HTTP requests with your colleagues, by providing you with a shortened URL like: https://paw.pt/aT4yn5QF
Paw is a full-featured HTTP client for Mac
There are also many situations where you want to intercept HTTP traffic to see what’s going on between your server and a client. To inspect traffic on a local network, you should try mitmproxy, a CLI tool that allows you to see the status of requests, inspect, and redirect traffic. The graphical version of it is Charles; it’s full-featured and has many years of experience already, but I have to say the Java-like interface is terribly 2000'. If you need to inspect traffic between remote machines, RequestBin is nice (it requires a free Runscope account).
Among hacking tools, I have a crush on ngrok. It exposes your local server to the (remote) internet. It’s a small idea that probably many of us have had, but it’s incredibly well executed! It’s the way to go if you want to give access to your localhost server to remote working colleagues, or test incoming webhooks.
Definition of the API
Defining your API is like filling the gap between development and testing. It defines the contract you — the provider — have with the consumers. API definitions act as the header files would in a programming language, and are a great way to imagine your API before implementing it.
You may just describe your API in your own words and style in a Markdown file, or with a nicer interface like readme.io, but I would recommend using one of these 3 description formats:
- Swagger is based on YAML or JSON, and it’s probably the most popular one. The spec supports JSON Schema which is an awesome way to describe your content. It comes with open-source tools to generate documentation and mock servers, but sadly the UIs available are too data-oriented for my taste and often forget usability.
- API Blueprint is a Markdown-based, human friendly language to describe your APIs, that is pitched by the authors as “a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown”. It’s maintained by Apiary which will host your API documentation, and is supported by many open-source community projects.
- RAML claims it is “a simple and succinct way of describing practically RESTful APIs”, and probably has the softest learning curve. It’s similar to Swagger, supports JSON Schema and inline examples.
Hypermedia and Linked Data
One may argue that since having a uniform interface is one of the constraints of the REST architecture, there’s no point having a frozen documentation and a versioning scheme. Clearly, HTTP and the web have been designed as a way to interact with data without a predefined data schema, and that’s unarguably a great thing.
GitHub has a nice living example of hypermedia API, with a root endpoint referencing objects by their URL. In theory, one could use such an API without knowing the endpoints before: that’s where the need for self-explanatory resources (objects) comes.
If this may sound overkill when you just start developing your API, JSON-LD is a good way to formally discribe the linking between objects and give consumers access to the descriptive metadata.
John Lennon described in a JSON-LD object
If JSON-LD and JSON Schema share the goal of structuring JSON data, they may be very much complementary as the latter focuses on describing the type structure of objects.
The “Artist” type described using JSON Schema
I would be tempted to add a link to a JSON Schema file from the resources described in JSON-LD!
If you’re at the stage of monitoring your API, you’re already pretty far down the road. Otherwise, I’d frankly recommend you to focus on building a product before thinking about this part.
I often talk with the Mashape team, so I’ll start with their new toys. KONG is a layer on top of NGINX that will add many features for your API, including Rate-Limiting, Auth, Caching, Logging, and more via plugins. It nicely plays with Galileo, their service for API analytics. You may also check Runscope that will monitor your API, make sure it passes the validators you configured and send you real time alerts in case of failure. What I see as a downside is the need to point your production API traffic through it.
I hope this list was helpful. For me it’s also a way to give back a tiny bit to my favorite tools, after reading many articles mentioning Paw. If you like it, I hope you’ll share your thoughts in the comments and share this with anyone you think might find it useful.
Originally posted on Medium / The RESTful Web