APIs:The good, the bad, the ugly

@MicheleTitolo

What we’ll cover

Documentation

The Good

It exists

Bonus: it’s interactive

I/O Docs

The Bad

Docs aren’t updated

The Ugly

Documentation?

URLs

The Good

Consistency

/users/22445/products/3156/movies/127/times

The Bad

Inconsistency

/users/22445/reviews/3156/times/127

Not review or time id’s

The Ugly

“Send GET to /remove to delete”

Payloads

The Good

You have all the data you need

The Bad

Endpoint “id” field

/products id

/products/:id productID

/cart product_id

Yes, this actually happened

Change

We expect certain things

...like image urls having http://

...like dates sent in the same format

We expect certain thingsto not change

The Ugly

JSON containing HTML

Unstable

Authentication

The Good

HTTP Basc Auth over SSL

...when SSL is secure

OAuth

The Bad

OAuth

The Ugly

Authorization

The Good

App requests permissions

The Bad

A single API key

The Ugly

Authorization?

goto fail;

Errors

The Good

Error codes

Error message in response

Human readable error message

The Bad

“There was an error”

The Ugly

Caching

The Good

Using one of the standards

Cache-Control

If-Modified-Since

etags

The Bad

Manually processing data

The Ugly

Caching

In Summary

Consistency

Conventions

Simple

Questions?@MicheleTitolo

• JSONSchema, RAML, API Blueprint,

• HTTP 1.1 Spec: http://www.w3.org/Protocols/rfc2616/rfc2616.html

• Charles, Postman

• http://runscope.com, also http://newrelic.com for backend analytics

• Versioning: http://apiux.com/2013/05/14/api-versioning/

Q&A Resources