Chapter 6: Sketching APIs

Design and Build Great Web APIs — by Mike Amundsen

In this chapter we will learn how to turn those documents/artifacts we created in the previous chapters into a working API by converting our design into an implementation. We will learn how to create quick API sketches and to make a prototype of our API.

Sketching and prototyping is a way to test ideas. We can create low-fidelity samples that we can show others and make adjustments and improvements all without having to write a lot of code.

The Advantages of Sketching

Sketches are simple, stand-alone snippets that convey your ideas without the need to write actual code and deploy it on some server somewhere. Even if you don’t plan to go through lots of iterations of your sketching, you can take advantage of the low-tech nature of cases and ignore the corner cases, exceptions and other minor details.

Sketching makes it easier for the stakeholders to “see” what the API will look like and to provide quick feedback and suggestions on how to improve the API.

One good thing about these easy-to-make sketches are that they are disposable. You can always make multiple iterations before you land of a “good enough” design to present to your stakeholders.

You could use tools like Apiary Blueprint to create your sketches.

Different Formats, Different API

One of the formats, the author uses for his early sketches is HTML. It makes it easy to visualize the way resources connect to each other, and it also makes it possible to share the sketches with others on the team.

There is another format application/forms+json that can be used as well.

Using different formats can lead to recognizing different patterns in your API and different ways to express the sequence diagram. It’s valuable to test things out, show them to others and get feedback on what implementations seem too complex, too verbose or just too confusing for your target audience.