api design workflows

jakub@apiary.io

API Design Workflow

Overview

• Why are APIs different?

• Why are APIs bad?

• How to fix that?

* APIs = REST/HTTP APIs

Jakub Nesetril

• backend dev (~8 years)

• frontend dev (~5 years)

• founder of Apiary

Apiary

• API Design, Documentation & Testing Tools

• 10,000s APIs, developers, companies, ideas

• Largest API community worldwide

What is an API?

API is UI to DataUser Experience

Design

Subjective

Simplicity

Conversion RatesEmotions

ProductivityUsability Studies

Culturally Dependent

Hackathons

Great! Make good design, right?

Empathy is HARD!

Provider Consumer

Uptime

Caching

Security

Maintenance

Versioning

ValidationCan It Be Done?

Debugging

Support

TTFHW

Example

Latency

Java

Rails

Scala

Erlang

jQuery

ObjC

AngularJS

So what?

Traditional API Development

Design

Implementation

Customer

3-6 weeks

3-6 months

Problem: API providers don't understand API consumers

(and vice versa)

Want good APIs? !

Empower the Frontend

Let's turn that on it's head

Design

Implementation

Customer

Frontend developer co-designs an API

Backend developers get implementation specs

(in form of tests)

API Blueprint

• human-readable & human-writable

• based on Markdown, you already know it

• structured reasoning about APIs

# Message of the Day API A simple [MOTD](http://en.wikipedia.org/wiki/motd) API. !# Message [/messages/{id}] This resource represents one particular message identified by its *id*. !## Retrieve Message [GET] Retrieve a message by its *id*. !+ Response 200 (text/plain) ! Hello World! !## Delete Message [DELETE] Delete a message. **Warning:** This action **permanently** removes the message from the database.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

API Blueprint

demo

API Lifecycle

Design

Prototype

Implementation

Delivery

Feedback

What happens when you're offline?

git workflow demo

Frontend

Backend

Contract

Concurrent Development

mocks

tests

Apiary for Teams

• roles

• integration with GitHub

• custom docs visuals

• teams up to 20 users

Random Notes

• PMs aren’t technical, Dev’s aren’t customer-focused

• The hardest thing about APIs is a push to get things right the first time

• For larger teams, create a “style guide”

PMs aren’t technical, Dev’s aren’t customer-focused

The hardest thing about APIs is a push to get things right

the first time

For larger teams, create a “style guide”

Source Code

Format: https://github.com/apiaryio/api-blueprint

Testing: https://github.com/apiaryio/dredd

JS SDK: https://github.com/apiaryio/apiblueprint-sdk

@apiaryio http://apiary.io/

!

@jakubnesetril

Thank You Questions?