a bird's eye view on api development
TRANSCRIPT
Birds eye view on:API DEVELOPMENT
WHO ?
Frederick Vanbrabant Software engineermadewithlove
Dries Vints@driesvints
Freek Van der Herten@freekmurze
phpantwerp.be
{ "id": 1, "title": "7 Things You Should NEVER Do to a potato", "subtitle": "you will never believe nr 4", "body": "Some body copy that will go on in great detail", "comments": [{ "id": 1, "body": "woah this changed my life" }, { "id": 2, "body": "I will never look at stuff in the same way" }]}
GET /getblogpost/1
Why is this not so great ?
Url is kinda structure less
What if we get loads of articles?
What if we get loads of comments?
Damn, we need to write documentation
Is this the best way to pinpoint a resource
GET /getblogposts/1
Let's look at that endpoint
HTTP verb
Endpoint
HTTP verbs
HTTP verbs
HTTP != CRUD
HTTP verbs
Verb Return HTTP Code
POST 201
Sends a payload to the server,Returns an empty body.
HTTP verbs
Verb Return HTTP Code
POST 201
POST /posts
{ "title": "Why cheese is better then real friends", "body": "People only stand in the way of you and your cheese!"}
Post body
HTTP verbs
Verb Return HTTP Code
GET 200
Does not send a payloadReturns a collection of or a single resource
HTTP verbs
Verb Return HTTP Code
GET 200
GET /posts/2
{ "title": "How to fake your own death", "body": "You can buy cheese with the insurance money!"}
Return body
HTTP verbs
Verb Return HTTP Code
PUT 204
Updates a resource (needs the entire object)Returns an empty body.
HTTP verbs
Verb Return HTTP Code
PUT 204
PUT /posts/2
{ "title": "Help I'm stuck in a keynote making factory", "body": "Send cheese!"}
Put body
HTTP verbs
Verb Return HTTP Code
PATCH 200
Accepts instructions to update the resourceReturns the resource
Wait what?
Accepts instructions to update the resourcereturns the resource
PATCH /artists/kanye/[ { "op": "replace", "path": "artists/kanye/cars", "value": 7 },]
Wait what?
Accepts instructions to update the resourcereturns the resource
PATCH /artists/kanye[ {"cars" : 7}]
Content-Type: application/partial-update-json
HTTP verbs
Verb Return HTTP Code
DELETE 204
Removed the resourceReturns an empty body.
HTTP verbs
Verb Return HTTP Code
DELETE 204
DELETE /posts/1
HTTP CODE
HTTP CODE
Range 1XX - Information
Code What it means
100 continue
101 Switching Protocols
102 Processing
HTTP CODE
Range 2XX - Success
Code What it means
200 Ok
201 Created
202 Accepted
HTTP CODE
Range 3XX - Redirection
Code What it means
301 Moved
300 Multiple Choices
HTTP CODE
Range 4XX - Client error
Code What it means
400 Bad Request
401 Unauthorized
404 Not found
HTTP CODE
Range 5XX - Server error
Code What it means
500 Internal Server Error
503 Service Unavailable
504 Gateway Timeout
HTTP HEADERS
HTTP HEADERS
Send on each request and response
Meta data to the call
Can define custom headers
HTTP HEADERS
GET / HTTP/1.1
Host: www.google.comConnection: keep-alivePragma: no-cacheCache-Control: no-cacheUpgrade-Insecure-Requests: 1User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/X-Chrome-UMA-Enabled: 1X-Client-Data: CIS2yQEIpbbJAQjEtskBCOCUygEI+pjKAQjznMoBAccept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8Accept-Encoding: gzip, deflate, sdchAccept-Language: nl,en;q=0.8Cookie: *Cookie data*
Request
HTTP HEADERS
Status: 200 (OK)
Date: Fri, 08 Jul 2016 13:59:05 GMTExpires: -1Cache-Control: private, max-age=0Content-Type: text/html; charset=ISO-8859-1X-Xss-Protection: 1; mode=blockX-Frame-Options: SAMEORIGINSet-Cookie: NID=81=x8aqWN0zsVHK2QcLEZca6603H8BYJxXP6bfjQl0cT82iM4j7fE3V9wH2qbpXW0DAAPL3G56n9ID-H_RCP-w9eVxA-mu9XV-oX-oE00qrVwRgzXV334c7XpsX2DDuTdcq; expires=Sat, 07-Jan-2017 13:59:05 GMT; path=/; domain=.google.be; HttpOnlyAccept-Ranges: noneVary: Accept-EncodingTransfer-Encoding: chunked
*HTML, JSON, XML OR WHATEVER*
Response
What about the endpoint
GET /getblogposts/1
What about the endpoint
GET /posts/1
What about the endpoint
GET /posts/1
Nouns are good, verbs are bad
Use plurals
What about the endpoint
GET /posts/1
GET /posts/1/comments
GET /posts/1/comments/15
OR
GET /comments/15
What about the endpoint
GET /posts
GET /posts/slugs-are-allowed
What about the endpoint
GET users/4b3403665fea6/posts/4b340550242239
What about the endpoint
Endpoint structure != database structure
We still 200 ?
Let's check out that body?
{ "id": 1, "title": "7 Things You Should NEVER Do to a potato", "subtitle": "you will never believe nr 4", "body": "Some body copy that will go on in great detail", "comments": [{ "id": 1, "body": "woah this changed my life" }, { "id": 2, "body": "I will never look at stuff in the same way" }]}
Let's use a standard
Battle tested and growing up to be the standard
{ "count": 87, "next": "http://swapi.co/api/people/?page=2", "previous": null, "results": [ { "name": "Luke Skywalker", "height": "172", "mass": "77", "hair_color": "blond", "skin_color": "fair", "eye_color": "blue", "birth_year": "19BBY", "gender": "male", "homeworld": "http://swapi.co/api/planets/1/", "films": [ "http://swapi.co/api/films/6/", "http://swapi.co/api/films/3/", "http://swapi.co/api/films/2/", "http://swapi.co/api/films/1/", "http://swapi.co/api/films/7/" ], "species": [ "http://swapi.co/api/species/1/" ], "vehicles": [ "http://swapi.co/api/vehicles/14/", "http://swapi.co/api/vehicles/30/" ], "starships": [ "http://swapi.co/api/starships/12/", "http://swapi.co/api/starships/22/" ], "created": "2014-12-09T13:50:51.644000Z", "edited": "2014-12-20T21:17:56.891000Z", "url": "http://swapi.co/api/people/1/"
{ "count": 87, "next": "http://swapi.co/api/people/?page=3", "previous": "http://swapi.co/api/people/?page=1", "results": [ .... ]}
Links ?
page-based
{ "count": 30, "next": "http://swapi.co/api/people/?offset=60&limit=30", "previous": "http://swapi.co/api/people/?offset=0&limit=30", "results": [ .... ]}
Links ?
offset-based
{ "count": 87, "next": "http://swapi.co/api/people/?cursor=1374004777531007833", "previous": "http://swapi.co/api/people/?cursor=2627305797328905258", "results": [ .... ]}
Links ?
cursor-based
{ "name": "Luke Skywalker", "height": "172", "mass": "77", "hair_color": "blond", "skin_color": "fair", "eye_color": "blue", "birth_year": "19BBY", "gender": "male", "homeworld": "http://swapi.co/api/planets/1/", "films": [ "http://swapi.co/api/films/6/", "http://swapi.co/api/films/3/", "http://swapi.co/api/films/2/", "http://swapi.co/api/films/1/", "http://swapi.co/api/films/7/" ], "species": [ "http://swapi.co/api/species/1/" ], "vehicles": [ "http://swapi.co/api/vehicles/14/", "http://swapi.co/api/vehicles/30/" ], "starships": [ "http://swapi.co/api/starships/12/", "http://swapi.co/api/starships/22/" ], "created": "2014-12-09T13:50:51.644000Z", "edited": "2014-12-20T21:17:56.891000Z", "url": "http://swapi.co/api/people/1/"}
Wait I can't have nested-resources?
Wait I can't have nested-resources?
This is not really HTTP now is it ?
Think about howyou surf the webThat's pretty nice right ?
HATEOASHypermedia as the Engine of Application State
HATEOAS Hypermedia as the Engine ofApplication State
{ "name": "Boba Fett", "height": "183", "mass": "78.2", "hair_color": "black", "skin_color": "fair", "eye_color": "brown", "birth_year": "31.5BBY", "gender": "male", "homeworld": "http://swapi.co/api/planets/10/", "films": [ "http://swapi.co/api/films/5/", "http://swapi.co/api/films/3/", "http://swapi.co/api/films/2/" ], "species": [ "http://swapi.co/api/species/1/" ], "vehicles": [], "starships": [ "http://swapi.co/api/starships/21/" ], "created": "2014-12-15T12:49:32.457000Z", "edited": "2014-12-20T21:17:50.349000Z", "url": "http://swapi.co/api/people/22/"
HATEOAS
"I'm not going to make 500 calls just to get somecomments"
HATEOAS
"I'm not going to make 500 calls just to get somecomments"
GET /films
GET /films/4,5,6
HATEOAS
"Can't you just add the resources to the url?"
GET /articles/1?include=comments,likes
QUERY PARAMETERS
Filter the response to what's valid on the query
GET /cheeses?type=brie,cheddar
GET /cheeses?type[]=brie&type[]=cheddar
AUTH
AUTH
AUTH
- HTTP Basic- JWT- OAuth 2.0
HTTP Basic
- Super easy- Not super safe
JWT (Json web tokens)
- No database hassle- Needs some knowledge
JWT (Json web tokens)
ServerClient
make new callswith the token
Return token
Send credentials
JWT (Json web tokens)
https://jwt.io/
OAuth2
- Very secure and very flexible- Can be daunting to setup
OAuth2
ServerClient
make new callswith the token
Return token +Refresh token
Send credentials
OAuth2
ServerClient
make new callswith the token
Return token +Refresh token
Send refresh token
API VERSIONING
API VERSIONING
YOU SHOULD NOTHAVE TO VERSION AN
API!
API VERSIONING
BUT YOU WILL HAVETO EVENTUALLY
API VERSIONING
GET /api/v1/artists/taylor-swift
API VERSIONING
GET /api/v1/artists/taylor-swift
The good The bad
Easy to implement Routes should not change
Easy to see what versionwe are on
Meta data should be in aheader
API VERSIONING
GET /api/artists/taylor-swiftx-api-version: 1
API VERSIONING
The good The bad
Meta data is in the header Custom header ... ?
Url does not change You need documentation
Url does not change
GET /api/artists/taylor-swiftx-api-version: 1
API VERSIONING
GET /api/artists/taylor-swiftAccept: application/vnd.website.v1+json
API VERSIONING
The good The bad
Meta data is in the header Harder to test
Standard http header You need documentation
GET /api/artists/taylor-swiftAccept: application/vnd.website.v1+json
Random TIPS
START WITH DOCUMENTATION
Random TIPS
LOOK AT THE USER FIRST, NOT THE TECH(A GOOD API DOES NOT NEED TO BE REST)
Random TIPS
TYPE CAST YOUR RETURN VALUES
Random TIPS
CONSISTENCY IS KING
Random TIPS
TEST YOUR ENDPOINTS
Random TIPS
NEVER TRUST YOUR USERS
Random TIPS
Use PHP?
Laravel: https://github.com/dingo/apiVanilla: https://thephpleague.com https://github.com/spatie
Use Python?
Django: http://www.django-rest-framework.org
Random TIPS
Want to know more?
This talks in text form:https://blog.madewithlove.be/post/birdseye-view-on-api
Phil Sturgeon's book:
https://leanpub.com/build-apis-you-wont-hate
Great O'Reily book RESTful Web APIs:
http://shop.oreilly.com/product/0636920028468.do
Questions!
Twitter: TheEdonian
THANKS !