API Design

EVERYTHING YOU NEED TO KNOW BUT HAVE NEVER BEEN TOLD

WORKING DRAFT
Last Modified
Printed
(…) you have a long list of URLs and no consistent pattern making it difficult for developers to learn
how to use your API (THE SWAMP OF POX)

Last Modified
Printed
McKinsey & Company2
(Good) API Design

MISSION

• A standard authentication mechanism

Last Modified
• Flexibility for business
• Speed ​in delivering new functionality
• Increase REST compatibility (easy to use)
• Design for Operations
• Developers Playground

Printed
USE THE FAÇADE PATTERN WHEN YOU WANT TO PROVIDE A SIMPLE
INTERFACE TO A COMPLEX SUBSYSTEM. SUBSYSTEMS OFTEN GET MORE
COMPLEX AS THEY EVOLVE
Design Patterns – Elements of Reusable Object-Oriented Software (Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides)

McKinsey & Company3

Attribute names and Output format

Last Modified
Microdata & SEO

Printed
McKinsey & Company4
A URI Template is a compact sequence of characters for describing a range of Uniform Resource
Identifiers through variable expansion (RFC 6570)

Last Modified
ns
In summary…

io
ct
lle
co
Use two base URLs per
resource

/dogs
/dogs/1234

t
en
Keep verbs out of your

me

Printed
base URLs

el
Use HTTP verbs to
operate on the collections
and elements

McKinsey & Company5

Use HTTP verbs to operate on the collections and elements (1/2)

Last Modified
Printed
McKinsey & Company6
Use HTTP verbs to operate on the collections and elements (2/2)

idempotent methods, they are HTTP methods which can be

called multiple times and they will produce the same result 

safe methods are HTTP methods that do not modify the

Last Modified
resource

PATH: a side note...

DON’T DO RED
PUT /users/123/email
new.email@example.org

getting better
PUT /users/123
{ "email": "new.email@example.org" }

Printed
PATCH /users/123
{ "email": "new.email@example.org" }

BUT GREEN IS GOOD...

PATCH /users/123
[{ "op": ”replace", "path": "/email",
"value": " new.email@example.org" }]

McKinsey & Company7

Most problem domains include conceptual relationships in addition to simple properties. The natural
construct for representing relationships in HTTP is the link

HATEOAS

Last Modified
HAL

Printed
McKinsey & Company8
API examples

Last Modified
Printed
[…]

McKinsey & Company9

Sweep complexity behind the ‘?’

Last Modified
https://www.google.com/search?q=red+dog

Printed
McKinsey & Company10
URI Design
Collections /products
Element /products/8d8d123a-ba34-4c42-8f35-3c0169f3972f
Relations /products/SqrVhuCsQlmoiiIn5Pgpiw/reviews
/reviews?q=product:SqrVhuCsQlmoiiIn5Pgpiw
HTTP GET PUT PATH POST DELETE

Last Modified
Content JSON
Pagination ?start=10&rows=10
/products?q=description:consignado
Search/Filtering /search?q=consignado
Partial Content /products?q=description:analgesic&fl=id,name
POST /customers/CQ8FDQoPDgYBBAQHBAoOBQ/password
{location: /customers/CQ8FDQoPDgYBBAQHBAoOBQ/?confirmationCode=ba34n5Passpiw1g}
PATH /customers/CQ8FDQoPDgYBBAQHBAoOBQ/password?confirmationCode=ba34n5Passpiw1g
{ password: “123456” }

Printed
PUT /user/starred/:owner/:repo
Verbs (?) Status: 204 No Content
Versioning /v2/products

McKinsey & Company11

Handling Errors

STATUS
200 OK
201 Created
202 Accepted

Last Modified
204 No Content
301 Moved Permanently
400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed

Printed
409 Conflict
410 Gone
413 Request Entity Too Large
420 Enhance your calm
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable

McKinsey & Company12

Pagination and partial response (1/2)

Last Modified
https://api.company.com/v2/customers?start=2&rows=50&fields=id,name

Printed
Limit? 50
Default: 10

McKinsey & Company13

Pagination and partial response (2/2)

Last Modified
Printed
McKinsey & Company14
OAuth: One authorization to rule then all

Last Modified
Printed
McKinsey & Company15
OAuth: One authorization to rule then all (Authorization Code Flow)

https://api.company.com/v2/oauth/authorize?client_id=someAppID&redirect_uri=http://clientHost/&scope=read&response_type=code

Last Modified
https://company.com http://clientHost/?code=ufXpQ8

[redirect]

curl https://api.company.com.br/v2/oauth/token -d "code=

ufXpQ8&client_id=someAppID&client_secret=PJHh01pW&redirect_uri=http://cli
entHost/&grant_type=authorization_code"

{ "token_type": "Bearer", "expires_in": 3600, "access_token": "8c698e20-

Printed
79c0-4cf7-a9ee-a9dac4ff8f0c", "scope": ”read", "refresh_token":
"kq7WiKzc299uETMGRdVqF2Hp0ldo8lNFusYIkqWuFO8" }

https://api.company.com//products?q=description:analgesic?access_token= 8c698e20-79c0-4cf7-a9ee-a9dac4ff8f0c

McKinsey & Company16

Developers Playground

Last Modified
GET /products/5480

Printed
McKinsey & Company17