Things you should know

Building a

Public API

}

During

Before

After

@yonatanm

Outbrain

Outbrain

>0.5B190BUnique Visitors

RecommendationS per Month

* min {control on usage}* max {responsibility}* decisions.exist {_.takeAtDay1}

Quiz #1

???

Product

API

Users

Answer

Developers

Product

API

Users

Quiz #2

???

Product

API

U.X.

Answer

Product

API

Resources && URIS

U.X.

Be consistently consistent

* HTTP methods* HTTP codes* Headers* Authentication

No one likes surprises

Make your users feel at home

Use Standards:

Error handling

It is all about the Expectations

GET

POST

PUT

/customers/{id}

/customers

/customers

REQUEST

RESPONSE

customer

GET

customer

customer

customer

customer

*

200

201

200

To embed

GET /customers/1

GET /customer/1/orders

|| !to embed

GET /customers/1

Can we have both ?

To embed || !to embed ?

SimpleAll you need in one requestFewer transactions

FastBuilding blockflexibilityCacheable

!to embed

to embed

and do it right ?

*

Yes We Can !

GET /customers/1

GET /customers/1?embed=orders

Yes We Can #2

GET /customers/1

Quiz #3

???

Product

API

U.I.

Answer

Documentation

Product

API

U.I.

Documentation

apiary.ioSwagerMashape and More...

* Be consistent* Focus on Resources* Less > More* Examples

"

** Sand-box ? +1

Documentation

Documentation

Documentation

* UX interactions* UI documentation* Ideas to new features* Bugs

Eat your own dog food

Tip #1

Tip #2

What's wrong with using DB IDs as your entity IDs?

GET /customers/1

Authorizationprivacy , your privacy

Bi-Directional mapping using secret key

HOW?

Tip #2

Add another column in the DB

2784732184569

1

Like a version

OR

/SUPPORT/multiple/VERSIONS/v2.5/

/SELL/your/soul/to/backwards/compatibility

URI should control identity not presentation

http://bit.ly/1Mo0yXF

===>GET /customer/1 HTTP/1.1Accept: application/outbrain.customer-v2.5+json