@simonrenoult | srenoult@octo.com

Simon Renoult

RESTful API Design.

A.K.A.

RESTful API in 15mn

API.

Whaaaat?

GET /people?first_name=John

> 200 OK
[{
  "id":"007",
  "first_name": "John",
  "last_name": "Lennon",
  "age": 76,
  "gender": "M",
  "albums": "/v1/people/007/albums"
}]

API.

Why?

System interoperability

External innovation

Business opportunities

API.

RESTful?

Developer oriented

Easy to reuse

URLs.

It's all about affordance.

Use HTTP verbs.

GET

POST

PUT

DELETE

PATCH

Read something. No side-effect.

Create something.

Update or create something.

Remove something.

Update (partially) something.

Give me a name.

Verbs?

And a good one.

No, HTTP takes care of that

Resource

We manipulate (HTTP verb) a resource (noun)

Consistent case.

CamelCase

Snake_case

Spinal-case

GET /v1/orders?userId=007

GET /v1/orders?user_id=007

GET /v1/orders?user-id=007

Just... Be consistent.

You are not alone.

Root object is a collection.

/client

Nop.

/clients

Yes!

Version everything.

Things will change.

In the headers

As a query parameter

In the URL path

Nop!

Meh...

Yes!

HTTP status codes.

HTTP for the rescue.

Success.

200

201

204

206

Created

No content

Partial content

GET /pokemons

POST /pokemons

DELETE /pokemons

GET /pokemons

Client.

400

401

403

404

Bad request

Unauthorized

Forbidden

Not Found

Server.

500

503

Internal Server Error

Service Unavailable

Query strings.

Don't be smart. Be standard.

Search.

GET /v1/products/search?name=la*

Pagination.

GET /v1/products?range=0-24

Sort.

GET /v1/products?sort=foo&desc=bar

Partial response.

GET /clients/007?fields=name,address(street)

Other key concepts.

A.K.A. "Fourre-tout"

Non-resource scenarios.

When real life hurts.

POST

Verbs

Manipulate actions instead of resources

Stay RESTful-ish. POST is :

not safe
not idempotent

Search cross-resource

Activate or deactivate something

Send a password recovery email

POST /v1/search

Make it RESTful. You can do it.

POST /v1/recovery-email

Don't be RESTful at any price.

Be affordable first.

HATEOAS.

HAL

Hydra

JSON-LD

RFC5988

New kid in the block

Define a set of "standard" link

Cool kid in the block

Yet another kid in the block

That's just links.

Up to you guys...

Architecture.

Because it matters. A lot.

KISS.

Don't use business specific terms

One way to do things

Design for your clients, not your data

Design for the many, allow the few (80-20)

Granularity.

Not too big. Not too thin.

One URL, one resource

GET /clients/007
{
  "id":"007",
  "name":"Bond",
  "address":"/v1/addresses/362"
}

GET /addresses/362
{
  "id":"123",
  "street":"Avenue des Champs-Elysées",
  "country": "/v1/countries/839"
}

One URL, one content

GET /clients/007
{
  "id":"007",
  "name":"Bond",
  "address": {
    "street-number":"50",
    "street":"Avenue des Champs-Elysées,
    "country:"france"
  },
  "articles": [{
    "id":"ab3423fds",
    "name":"foo",
    "description":"foo bar"
  }],
  "comments":[{
    ...
  }],
  "private-messages":[{
    ...
  }]
}

Security.

HTTPS everything

OAuth2/OIDC no matter what

API domain names.

https://api.fakecompany.com

https://api.sandbox.fakecompany.com

https://developers.fakecompany.com

https://oauth2.fakecompany.com

https://oauth2.sandbox.fakecompany.com

Documentation first.

An API is only as good as its documentation.

Curl

Swagger

Always provide curl samples

Open API Spec. (fev 2016)

Conclusion

Use HTTP.

Be affordant.

Ship it.

Questions?

Thanks.

Useful resources

http://vinaysahni.com/best-practices-for-a-pragmatic-restful-api

https://httpstatuses.com/

Design

Tools

http://blog.octo.com/designer-une-api-rest