How to build APIsTarget - Dan Cundiff (@pmotch) - MHacks 2016

What are APIs?

Why do companies have them?

Building APIs

We’re really talking about building web apps.

● We know how to test web apps● We know how to scale web apps● Infra-as-code● Continuous integration● Continuous delivery● Immutable infrastructure● etc

Designing APIs

Use an spec framework:● OpenAPI (aka Swagger)● API Blueprint● RAML

Design-first approach using API spec.

About REST

There is no one REST.

There are choices to make.

Collections of resources

Plural noun (let the http method be the verb)

/cars/

5 things I can do to that collection:

● GET /cars/v1/ - list of cars● POST /cars/v1/ - create a car● GET /cars/v1/{car_id} - get a car● PUT /cars/v1/{car_id} - update a car● DELETE /cars/v1/{car_id} - delete a car

Version after collection:

/cars/v1/

● Version your APIs● Breaking change = new

major version● Just follow semver.org

Filter the list:

GET /cars/v1?model=ford&color=red

For attributes that don’t appear in the data model, do:

GET /cars/v1/search?some_attribute_not_included_in_data_model=xyz

Even transactional events are collections (e.g. sending an email, a door opening, etc.)

POST /door_openings/v1● POSTs and GETs● Give door opening event

an id

POST /inventory_updates/v1● Avoid race conditions● Don’t do: PUT /inventory/{item_id}

Use paging for lists of things.

Use a chosen query param for partial responses.

Use normal http codes.

Use http caching.

Avoid:● Avoid XML● SOAP died in 2007

Use TLS, just do it.

istlsfastyet.com

Oauth, HMAC, basic auth.

● /cars/v1/{car_id}/owners/{owner_id} is cool too

● Rate limiting● Operators

API Gateways are useful.

Measure your APIs:● Centralize logs● Collect metrics

Monitor your APIs

You need a developer portal.

Dev portal:● docs● forums● key material, etc.

Making your API public or not

Reading:● Follow API devs on twitter● HN, API Evangelist, InfoQ

conf vids, etc

You should come work for Target.

Questions?