Web API's From Scratch - An Introduction to the API Development World - Speaker Deck

Tweet

Tweet

Slide 1

Slide 1 text

Lucas Mendes | Software Architect | @devsdmf WEB API’S FROM SCRATCH AN INTRODUCTION TO THE API DEVELOPMENT WORLD.

Slide 2

Slide 2 text

$ whoami

Slide 3

Slide 3 text

THE WEB

Slide 4

Slide 4 text

HISTORY

Slide 5

Slide 5 text

HOW IT WORKS ?

Slide 6

Slide 6 text

WEB API’S FROM SCRATCH

Slide 7

Slide 7 text

WHAT IS CLOUD COMPUTING ?

Slide 8

Slide 8 text

HOW THE BROWSER WORKS ?

Slide 9

Slide 9 text

HTTP PROTOCOL

Slide 10

Slide 10 text

DEFINITION

Slide 11

Slide 11 text

HTTP FLOW AND MESSAGES

Slide 12

Slide 12 text

WEB API’S FROM SCRATCH CLIENT PERFORMS A REQUEST TO A SERVER

Slide 13

Slide 13 text

WEB API’S FROM SCRATCH THE SERVER RETURNS A RESPONSE

Slide 14

Slide 14 text

WHAT ABOUT HTTPS ?

Slide 15

Slide 15 text

RESOURCES AND URI’S

Slide 16

Slide 16 text

WEB API’S FROM SCRATCH URL’S ▸ https://www.nuvemshop.com.br ▸ https://www.nuvemshop.com.br/planos-e-precos ▸ https://www.nuvemshop.com.br/blog?s=Loja+Virtual ▸ http://www.example.com:80/path/to/myﬁle.html? key1=value1&key2=value2#SomewhereInTheDocument

Slide 17

Slide 17 text

WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)

Slide 18

Slide 18 text

WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)

Slide 19

Slide 19 text

WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)

Slide 20

Slide 20 text

WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)

Slide 21

Slide 21 text

WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)

Slide 22

Slide 22 text

WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)

Slide 23

Slide 23 text

MIME TYPES

Slide 24

Slide 24 text

WEB API’S FROM SCRATCH MIME-TYPE STRUCTURE type/subtype

Slide 25

Slide 25 text

WEB API’S FROM SCRATCH COMMON MIME-TYPES ▸ text/plain ▸ text/html ▸ image/jpeg ▸ image/png ▸ audio/mpeg ▸ video/mp4 ▸ application/json

Slide 26

Slide 26 text

METHODS

Slide 27

Slide 27 text

WEB API’S FROM SCRATCH HTTP METHODS ▸ GET ▸ HEAD ▸ POST ▸ PUT ▸ PATCH ▸ DELETE ▸ OPTIONS ▸ and some others…

Slide 28

Slide 28 text

HEADERS

Slide 29

Slide 29 text

WEB API’S FROM SCRATCH HEADER GENERAL STRUCTURE Header-Name: header-value

Slide 30

Slide 30 text

GENERAL HEADERS

Slide 31

Slide 31 text

WEB API’S FROM SCRATCH GENERAL HEADERS ▸ Date: Wed, 21 Oct 2015 07:28:00 GMT ▸ Cache-Control: public, max-age=31536000 ▸ Connection: keep-alive

Slide 32

Slide 32 text

REQUEST HEADERS

Slide 33

Slide 33 text

WEB API’S FROM SCRATCH REQUEST HEADERS ▸ Accept: text/html, application/xml, application/json ▸ Accept-Encoding: gzip, compress ▸ Accept-Language: pt-BR ▸ Cookie: PHPSESSID=123123123; csrftoken=u32t4o3tb3gg43; ▸ User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36 ▸ Referer: https://developer.mozilla.org/en-US/docs/Web/JavaScript

Slide 34

Slide 34 text

RESPONSE HEADERS

Slide 35

Slide 35 text

WEB API’S FROM SCRATCH RESPONSE HEADERS ▸ Age: 60 ▸ Location: /redirect ▸ Server: Apache/2.4.1 (Unix) ▸ Content-Encoding: gzip

Slide 36

Slide 36 text

ENTITY HEADERS

Slide 37

Slide 37 text

WEB API’S FROM SCRATCH ENTITY HEADERS ▸ Content-Type: text/html ▸ Content-Length: 1024 ▸ Content-Language: pt-BR ▸ Content-Encoding: gzip

Slide 38

Slide 38 text

STATUS CODES

Slide 39

Slide 39 text

WEB API’S FROM SCRATCH 1XX - INFORMATION RESPONSES ▸ 100 Continue ▸ 101 Switching Protocol ▸ 102 Processing

Slide 40

Slide 40 text

WEB API’S FROM SCRATCH 2XX - SUCCESSFUL RESPONSES ▸ 200 OK ▸ 201 Created ▸ 202 Accepted ▸ 204 No Content ▸ 205 Reset Content

Slide 41

Slide 41 text

WEB API’S FROM SCRATCH 3XX - REDIRECTION MESSAGES ▸ 300 Multiple Choice ▸ 301 Moved Permanently ▸ 302 Found ▸ 304 Not Modiﬁed ▸ 307 Temporary Redirect

Slide 42

Slide 42 text

WEB API’S FROM SCRATCH 4XX - CLIENT ERROR RESPONSES ▸ 400 Bad Request ▸ 401 Unauthorized ▸ 403 Forbidden ▸ 404 Not Found ▸ 405 Method Not Allowed ▸ Too many other codes…

Slide 43

Slide 43 text

WEB API’S FROM SCRATCH 5XX - SERVER ERROR RESPONSES ▸ 500 Internal Server Error ▸ 501 Not Implemented ▸ 502 Bad Gateway ▸ 503 Service Unavailable ▸ 504 Gateway Timeout ▸ Too many others…

Slide 44

Slide 44 text

CORS

Slide 45

Slide 45 text

WEB API’S FROM SCRATCH PREFLIGHT REQUEST

Slide 46

Slide 46 text

WEB API’S FROM SCRATCH MAIN REQUEST

Slide 47

Slide 47 text

JSON

Slide 48

Slide 48 text

WHAT IS JSON ?

Slide 49

Slide 49 text

WEB API’S FROM SCRATCH SAMPLE JSON DOCUMENT { "name": "Lucas Mendes", "company": "Tienda Nube", "age": 23, "weight": 88.0, "likeCoffee": true }

Slide 50

Slide 50 text

WHY JSON ?

Slide 51

Slide 51 text

WEB API’S FROM SCRATCH WHY JSON ? ▸ Simplicity ▸ Readability ▸ Scalability ▸ Flexibility ▸ Is JavaScript !!

Slide 52

Slide 52 text

API’S

Slide 53

Slide 53 text

WHAT IS AN API ?

Slide 54

Slide 54 text

USE CASES

Slide 55

Slide 55 text

PUBLIC API’S

Slide 56

Slide 56 text

WHY EXPOSE YOUR API ?

Slide 57

Slide 57 text

DEVELOPERS AS CUSTOMERS

Slide 58

Slide 58 text

WEB API’S FROM SCRATCH COMPANIES WITH PUBLIC API’S

Slide 59

Slide 59 text

REST API’S

Slide 60

Slide 60 text

WHAT IS REST ?

Slide 61

Slide 61 text

WHY REST ?

Slide 62

Slide 62 text

WEB API’S FROM SCRATCH WHY REST ? ▸ Scalability ▸ Generality ▸ Technology Independence ▸ Latency (Caching) ▸ Security ▸ Encapsulation

Slide 63

Slide 63 text

HATEOAS

Slide 64

Slide 64 text

WEB API’S FROM SCRATCH HATEOAS Hypermedia As The Engine Of Application State

Slide 65

Slide 65 text

API DESIGN

Slide 66

Slide 66 text

TIENDA NUBE AS EXAMPLE DOMAIN

Slide 67

Slide 67 text

WEB API’S FROM SCRATCH TIENDA NUBE RESOURCES ▸ Customer ▸ Coupon ▸ Order ▸ Product ▸ Store

Slide 68

Slide 68 text

RESOURCES

Slide 69

Slide 69 text

WEB API’S FROM SCRATCH COLLECTION RESOURCE https://api.tiendanube.com/v1/customers

Slide 70

Slide 70 text

WEB API’S FROM SCRATCH INSTANCE RESOURCE https://api.tiendanube.com/v1/customers/182

Slide 71

Slide 71 text

BEHAVIOUR

Slide 72

Slide 72 text

WEB API’S FROM SCRATCH BEHAVIOUR ▸ GET ▸ POST ▸ PUT ▸ PATCH ▸ DELETE

Slide 73

Slide 73 text

WEB API’S FROM SCRATCH GETTING A COLLECTION RESOURCE Request: GET /customers  Accept: application/json Response: 200 OK [  {  "name": "Lucas Mendes",  "email": “[email protected]"  }  ]

Slide 74

Slide 74 text

WEB API’S FROM SCRATCH GETTING AN INSTANCE RESOURCE Request: GET /customers/182  Accept: application/json Response: 200 OK {  "name": "Lucas Mendes",  "email": "[email protected]",  "age": 23,  "ordersCount": 1,  "active": true  }

Slide 75

Slide 75 text

PUT VS POST

Slide 76

Slide 76 text

WEB API’S FROM SCRATCH PUT FOR CREATE Identiﬁer is known by the client: PUT /customers/clientSpecifiedId {  "name": "Lucas Mendes",  "email": "[email protected]",  "age": 23  }

Slide 77

Slide 77 text

WEB API’S FROM SCRATCH PUT FOR UPDATE Full replacement: PUT /customers/existingId {  "name": "Lucas Mendes",  "email": "[email protected]",  "age": 23  }

Slide 78

Slide 78 text

WEB API’S FROM SCRATCH POST FOR CREATE On a parent resource: POST /customers {  "name": "Lucas Mendes",  "email": "[email protected]",  "age": 23  } Response: 201 Created  Location: https://api.tiendanube.com/customers/182

Slide 79

Slide 79 text

WEB API’S FROM SCRATCH POST FOR UPDATE On instance resource: POST /customers/182 {  "name": "Lucas Mendes",  "email": "[email protected]",  "age": 23  } Response: 200 OK

Slide 80

Slide 80 text

PATCH AND DELETE

Slide 81

Slide 81 text

WEB API’S FROM SCRATCH UPDATE WITH PATCH Send only the changed ﬁelds: PATCH /customers/182 {  "name": "John Doe"  } Response: 200 OK

Slide 82

Slide 82 text

WEB API’S FROM SCRATCH DELETE A RESOURCE Empty body in request and response: DELETE /customers/182   Response: 200 OK

Slide 83

Slide 83 text

BASE URL

Slide 84

Slide 84 text

WEB API’S FROM SCRATCH BASE URL http(s)://api.tiendanube.com vs http(s)://www.tiendanube.com/api/

Slide 85

Slide 85 text

VERSIONING

Slide 86

Slide 86 text

WEB API’S FROM SCRATCH VERSIONING URL  https://api.tiendanube.com/v1/ vs. Media-Type  application/json;application&v=1 vs. Custom Header  API-Version: v1

Slide 87

Slide 87 text

RESOURCE FORMAT

Slide 88

Slide 88 text

WEB API’S FROM SCRATCH RESOURCE FORMAT - MEDIA TYPES ▸ Request: Accept header ▸ Response: Content-Type header ▸ application/json ▸ application/json, application/xml ▸ …

Slide 89

Slide 89 text

WEB API’S FROM SCRATCH RESOURCE FORMAT - CAMEL CASE "JS" in "JSON" = JavaScript Wrong: {  "user_name": "Lucas Mendes"  } Right: {  "userName": "Lucas Mendes”  }

Slide 90

Slide 90 text

WEB API’S FROM SCRATCH RESOURCE FORMAT - DATE/TIME/TIMESTAMP Use ISO-8601 Example: {  "createdTimestamp": "2017-10-20T21:39:37Z"  }

Slide 91

Slide 91 text

RESPONSE BODY

Slide 92

Slide 92 text

WEB API’S FROM SCRATCH RESPONSE BODY GET obvious What about POST ? Return the representation in the response when feasible Add override (?_body=false) for control

Slide 93

Slide 93 text

WEB API’S FROM SCRATCH RESPONSE BODY - CONTENT NEGOTIATION Use Accept header Header values comma delimited in order of preference GET /orders/18572  Accept: application/json, text/plain

Slide 94

Slide 94 text

WEB API’S FROM SCRATCH RESPONSE BODY - RESOURCE EXTENSION GET /orders/18572.json  GET /orders/18572.xml  GET /orders/18572.csv … Conventionally overrides Accept header

Slide 95

Slide 95 text

REFERENCES

Slide 96

Slide 96 text

WEB API’S FROM SCRATCH REFERENCES (LINKING) ▸ Distributed Hypermedia is paramount! ▸ Every accessible Resource has a unique URL. ▸ Replace IDs when possible.

Slide 97

Slide 97 text

WEB API’S FROM SCRATCH REFERENCES (LINKING) Instance Resource with Reference GET /orders/18572 {  "customer": {  "href": "https://api.tiendanube.com/v1/customers/182"  }  "itemsPrice": 165.72,  "shippingPrice": 20.00,  "totalPrice": 185.72  }

Slide 98

Slide 98 text

PAGINATION

Slide 99

Slide 99 text

WEB API’S FROM SCRATCH PAGINATION ▸ Collection Resources must support pagination query parameters ▸ Offset ▸ Limit GET /stores?offset=50&limit=10

Slide 100

Slide 100 text

PARTIAL REPRESENTATION

Slide 101

Slide 101 text

WEB API’S FROM SCRATCH PARTIAL REPRESENTATION ▸ Provide content ﬁltering by using query parameters GET /stores/57432?fields=email,domain

Slide 102

Slide 102 text

ERRORS

Slide 103

Slide 103 text

WEB API’S FROM SCRATCH ERRORS ▸ As descriptive as possible ▸ As much information as possible ▸ Developers are your customers

Slide 104

Slide 104 text

WEB API’S FROM SCRATCH ERRORS - SAMPLE ERROR RESPONSE Request: POST /coupons {  …  } Response: 400 Bad Request {  "errorCode": 7601,  "errorMessage": "The specified coupon code is already taken”,  "moreInfo": "https://developers.tiendanube.com/api/docs/errors/12345"  }

Slide 105

Slide 105 text

CACHE

Slide 106

Slide 106 text

WEB API’S FROM SCRATCH CACHE ▸ Use HTTP cache for client-side caching ▸ Use cache servers for increase the performance ▸ Return a 304 Not Modified when the resource is cached

Slide 107

Slide 107 text

SECURITY

Slide 108

Slide 108 text

WEB API’S FROM SCRATCH SECURITY GUIDE-LINES ▸ Avoid sessions when possible: ▸ Authenticate every request if necessary ▸ Be Stateless ▸ Authorize based on resource content, not on URL! ▸ Use existing protocol: ▸ HTTP Basic Authentication (only over SSL), OAuth, JWT

Slide 109

Slide 109 text

WEB API’S FROM SCRATCH SECURITY GUIDE-LINES ▸ Custom Authentication Scheme: ▸ Only if your API is private ▸ Only if you really, really know what are you doing ▸ Use API keys instead of username/passwords

Slide 110

Slide 110 text

WEB API’S FROM SCRATCH WHY USE API KEYS ? ▸ Limited Exposure ▸ Password reset ▸ Independence ▸ Speed ▸ Traceability

Slide 111

Slide 111 text

WEB API’S FROM SCRATCH 401 VS 403 ▸ 401 “Unauthorized” really means Unauthenticated ▸ “You need valid credentials for me to response to this request” ▸ 403 “Forbidden” really means Unauthorized ▸ “Ok, you have the credentials, but you’re not allowed to access this resource”

Slide 112

Slide 112 text

LOGGING

Slide 113

Slide 113 text

DOCUMENTATION AND SPECIFICATION

Slide 114

Slide 114 text

WEB API’S FROM SCRATCH DOCUMENTATION AND SPECIFICATION ▸ Specification first, code later ▸ Documentation and Specification are not the same thing ▸ Documentation must be concise with the implementation ▸ Always provide a changelog ▸ Provide one SDK at least

Slide 115

Slide 115 text

TIME TO DEMO

Slide 116

Slide 116 text

THANK YOU! Lucas Mendes  Software Architect at Tienda Nube  about.me/devsdmf We're hiring, join the crew!   bit.ly/work-at-tiendanube