Art of Building APIs

founder & CEO of ApiaryJakub Nesetril

THE ART OF BUILDING APIS

ONE SIZE DOES NOT FIT ALLThere is no simple way to solve API design.

Different groups of developers has different needs, usecases and workflows.

ART, NOT ROUTINEAPI is and interface. In 2000’s, we thought it was machine-machine interface. But in 2010’s, we know that it’s the interface to the developer behind the machine. Thus, building APIs is a lot like building UIs.

UI design is dominated by user-centered design. It involves the user into design workflow as soon as possible, often using wireframes.

But API design is still largely a waterfall approach - design-build-document everything upfront. Only then involve the user.

apiary.io

Mock > Use > Implement

Using a mock server allows to change the workflow: produce a wireframe quickly, then involve the customer. Implement once the design is finalized.

apiary.io

Mock > Use > Implement

Using a mock server allows to change the workflow: produce a wireframe quickly, then involve the customer. Implement once the design is finalized.

HOST: http://api.twitter.com/ --- Twitter API 3.0 ------Welcome to our API. Comments support Markdown syntax---

-- Retrieve Tweets --GET /tweets> Accept: application/json< 200< Content-Type: application/json{ "items": [ { "url": "/feed", "range":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 }] }

API BLUEPRINT

Apiary.io has a quick tool for describing APIs using a very light-weight DSL called API Blueprint.

apiary.io

Mock > Use > Implement

DocumentationTesting

Using this more structured approach gives you more benefits at once. Once you finish designing, your documentation and test suite are in sync.

TESLA MODEL SAmong other APIs that were documented in Apiary was Tesla Model S.

apiary.io

E-MAIL [email protected] TWITTER @apiaryio

PHOTO CREDITS

http://www.flickr.com/photos/ironrodart/4308675209/sizes/o/http://www.flickr.com/photos/30030574@N03/3633431964/