What They Should Tell You About API Development

Slide 1

Slide 1 text

What They Should Tell You About API Development @PHILSTURGEON ON APIS… AGAIN

Slide 2

Slide 2 text

No content

Slide 3

Slide 3 text

SOAP != Bad Just… annoying

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

Don’t confuse REST with a metric of quality

Slide 6

Slide 6 text

Making an API 100% REST is hard

Slide 7

Slide 7 text

http://martinfowler.com/articles/richardsonMaturityModel.html

Slide 8

Slide 8 text

Do you actually need REST?

Slide 9

Slide 9 text

Maybe RPC would be more appropriate

Slide 10

Slide 10 text

REST = Resources RPC = Commands

Slide 11

Slide 11 text

Using commands for resources sucks And vice versa

Slide 12

Slide 12 text

RPC REST GET /listCheeseburgers GET /cheeseburgers POST /createCheeseburger POST /cheeseburgers POST /updateCheeseburger PATCH /cheeseburgers/1 POST /deleteCheeseburger DELETE /cheeseburgers/1 POST /consumeCheeseburger ….

Slide 13

Slide 13 text

POST /SendUserMessage HTTP/1.1 Host: api.example.com Content-Type: application/json {"userId": 5,"message":"Hello!"}

Slide 14

Slide 14 text

POST /users/5/send-message HTTP/1.1 Host: api.example.com Content-Type: application/json {"message":"Hello!"}

Slide 15

Slide 15 text

POST /users/5/messages HTTP/1.1 Host: api.example.com Content-Type: application/json {"message":"Hello!"}

Slide 16

Slide 16 text

State Changes COULD be RPC

Slide 17

Slide 17 text

POST /trips/123/start HTTP/1.1 Host: api.example.com

Slide 18

Slide 18 text

POST /trips/123/finish HTTP/1.1 Host: api.example.com

Slide 19

Slide 19 text

POST /trips/123/cancel HTTP/1.1 Host: api.example.com

Slide 20

Slide 20 text

PATCH + State Machine

Slide 21

Slide 21 text

PATCH /trips/123 HTTP/1.1 Host: api.example.com Content-Type: application/json {"status":"in_progress"}

Slide 22

Slide 22 text

PATCH /trips/123 HTTP/1.1 Host: api.example.com Content-Type: application/json {"status":"complete"}

Slide 23

Slide 23 text

oh look ruby at a php conference

Slide 24

Slide 24 text

Sometimes a little RPC sneaks in...

Slide 25

Slide 25 text

POST /invitations/some-code/join HTTP/1.1 Host: api.example.com

Slide 26

Slide 26 text

There’s a reason Slack use RPC

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

DELETE /users/jerkface HTTP/1.1 Host: api.example.com

Slide 29

Slide 29 text

PATCH /users/jerkface HTTP/1.1 Host: api.example.com Content-Type: application/json {"status" : "kicked"}

Slide 30

Slide 30 text

PATCH /users/jerkface HTTP/1.1 Host: api.example.com Content-Type: application/json {"status" : “kicked", "kick_channel" : "catgifs"}

Slide 31

Slide 31 text

DELETE /channels/random/users/jerkface HTTP/1.1 Host: api.example.com

Slide 32

Slide 32 text

DELETE /channels/random/users/jerkface HTTP/1.1 Host: api.example.com Content-Type: application/json {"reason" : "kick"}

Slide 33

Slide 33 text

So probably RPC for commands then?

Slide 34

Slide 34 text

POST /channel.kick HTTP/1.1 Host: api.example.com Content-Type: application/json Authentication: Bearer moderator_token {"user" : "jerkface", "channel" : "catgifs"}

Slide 35

Slide 35 text

POST /channel.leave HTTP/1.1 Host: api.example.com Content-Type: application/json Authentication: Bearer user_token {"channel" : "catgifs"}

Slide 36

Slide 36 text

POST /user.ban HTTP/1.1 Host: api.example.com Content-Type: application/json Authentication: Bearer moderator_token {"user" : "jerkface"}

Slide 37

Slide 37 text

No content

Slide 38

Slide 38 text

No content

Slide 39

Slide 39 text

Document everything

Slide 40

Slide 40 text

Document FIRST

Slide 41

Slide 41 text

Test your docs!

Slide 42

Slide 42 text

No content

Slide 43

Slide 43 text

No content

Slide 44

Slide 44 text

Maybe you don’t need HATEOAS

Slide 45

Slide 45 text

http://martinfowler.com/articles/richardsonMaturityModel.html

Slide 46

Slide 46 text

Hypermedia helps APIs outlive the average startup

Slide 47

Slide 47 text

RAD makes most attempts at versioning entirely pointless

Slide 48

Slide 48 text

Don’t trust self- testing apps/services

Slide 49

Slide 49 text

Docker & Compose to the rescue!

Slide 50

Slide 50 text

TDD is the easiest way to build a complex HTTP API

Slide 51

Slide 51 text

Describe-it syntax helps you write complex tests easily

Slide 52

Slide 52 text

No content

Slide 53

Slide 53 text

No content

Slide 54

Slide 54 text

https://github.com/crysalead/kahlan

Slide 55

Slide 55 text

Don’t let clients hit staging for dev Again, probably use Docker/Vagrant

Slide 56

Slide 56 text

?include=literally, everything,in,the, goddam,database, what,is,happening, so,slow,help,me, database,server,is, on,fire,nothing,we,