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

Build scalable API's is not an easy task and to do that, we need to understand how the web works, including clients and servers, after get this, we can build API's that are easy to use and understand by you and other developers.

Presented at 11th Gama Academy Experience.

Transcript

1. Lucas Mendes | Software Architect | @devsdmf WEB API’S FROM SCRATCH AN INTRODUCTION TO THE API DEVELOPMENT WORLD.
2. $ whoami
3. THE WEB
4. HISTORY
5. HOW IT WORKS ?
6. WEB API’S FROM SCRATCH
7. WHAT IS CLOUD COMPUTING ?
8. HOW THE BROWSER WORKS ?
9. HTTP PROTOCOL
10. DEFINITION
11. HTTP FLOW AND MESSAGES
12. WEB API’S FROM SCRATCH CLIENT PERFORMS A REQUEST TO A SERVER
13. WEB API’S FROM SCRATCH THE SERVER RETURNS A RESPONSE
14. WHAT ABOUT HTTPS ?
15. RESOURCES AND URI’S
16. 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/myfile.html? key1=value1&key2=value2#SomewhereInTheDocument
17. WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)
18. WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)
19. WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)
20. WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)
21. WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)
22. WEB API’S FROM SCRATCH SYNTAX OF UNIFORM RESOURCE IDENTIFIERS (URI’S)
23. MIME TYPES
24. WEB API’S FROM SCRATCH MIME-TYPE STRUCTURE type/subtype
25. WEB API’S FROM SCRATCH COMMON MIME-TYPES ▸ text/plain ▸ text/html ▸ image/jpeg ▸ image/png ▸ audio/mpeg ▸ video/mp4 ▸ application/json
26. METHODS
27. WEB API’S FROM SCRATCH HTTP METHODS ▸ GET ▸ HEAD ▸ POST ▸ PUT ▸ PATCH ▸ DELETE ▸ OPTIONS ▸ and some others…
28. HEADERS
29. WEB API’S FROM SCRATCH HEADER GENERAL STRUCTURE Header-Name: header-value
30. GENERAL HEADERS
31. 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
32. REQUEST HEADERS
33. 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
34. RESPONSE HEADERS
35. WEB API’S FROM SCRATCH RESPONSE HEADERS ▸ Age: 60 ▸ Location: /redirect ▸ Server: Apache/2.4.1 (Unix) ▸ Content-Encoding: gzip
36. ENTITY HEADERS
37. WEB API’S FROM SCRATCH ENTITY HEADERS ▸ Content-Type: text/html ▸ Content-Length: 1024 ▸ Content-Language: pt-BR ▸ Content-Encoding: gzip
38. STATUS CODES
39. WEB API’S FROM SCRATCH 1XX - INFORMATION RESPONSES ▸ 100 Continue ▸ 101 Switching Protocol ▸ 102 Processing
40. WEB API’S FROM SCRATCH 2XX - SUCCESSFUL RESPONSES ▸ 200 OK ▸ 201 Created ▸ 202 Accepted ▸ 204 No Content ▸ 205 Reset Content
41. WEB API’S FROM SCRATCH 3XX - REDIRECTION MESSAGES ▸ 300 Multiple Choice ▸ 301 Moved Permanently ▸ 302 Found ▸ 304 Not Modified ▸ 307 Temporary Redirect
42. 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…
43. 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…
44. CORS
45. WEB API’S FROM SCRATCH PREFLIGHT REQUEST
46. WEB API’S FROM SCRATCH MAIN REQUEST
47. JSON
48. WHAT IS JSON ?
49. WEB API’S FROM SCRATCH SAMPLE JSON DOCUMENT { "name": "Lucas Mendes", "company": "Tienda Nube", "age": 23, "weight": 88.0, "likeCoffee": true }
50. WHY JSON ?
51. WEB API’S FROM SCRATCH WHY JSON ? ▸ Simplicity ▸ Readability ▸ Scalability ▸ Flexibility ▸ Is JavaScript !!
52. API’S
53. WHAT IS AN API ?
54. USE CASES
55. PUBLIC API’S
56. WHY EXPOSE YOUR API ?
57. DEVELOPERS AS CUSTOMERS
58. WEB API’S FROM SCRATCH COMPANIES WITH PUBLIC API’S
59. REST API’S
60. WHAT IS REST ?
61. WHY REST ?
62. WEB API’S FROM SCRATCH WHY REST ? ▸ Scalability ▸ Generality ▸ Technology Independence ▸ Latency (Caching) ▸ Security ▸ Encapsulation
63. HATEOAS
64. WEB API’S FROM SCRATCH HATEOAS Hypermedia As The Engine Of Application State
65. API DESIGN
66. TIENDA NUBE AS EXAMPLE DOMAIN
67. WEB API’S FROM SCRATCH TIENDA NUBE RESOURCES ▸ Customer ▸ Coupon ▸ Order ▸ Product ▸ Store
68. RESOURCES
69. WEB API’S FROM SCRATCH COLLECTION RESOURCE https://api.tiendanube.com/v1/customers
70. WEB API’S FROM SCRATCH INSTANCE RESOURCE https://api.tiendanube.com/v1/customers/182
71. BEHAVIOUR
72. WEB API’S FROM SCRATCH BEHAVIOUR ▸ GET ▸ POST ▸ PUT ▸ PATCH ▸ DELETE
73. WEB API’S FROM SCRATCH GETTING A COLLECTION RESOURCE Request: GET /customers
 Accept: application/json Response: 200 OK [
 {
 "name": "Lucas Mendes",
 "email": “devsdmf@gmail.com"
 }
 ]
74. WEB API’S FROM SCRATCH GETTING AN INSTANCE RESOURCE Request: GET /customers/182
 Accept: application/json Response: 200 OK {
 "name": "Lucas Mendes",
 "email": "devsdmf@gmail.com",
 "age": 23,
 "ordersCount": 1,
 "active": true
 }
75. PUT VS POST
76. WEB API’S FROM SCRATCH PUT FOR CREATE Identifier is known by the client: PUT /customers/clientSpecifiedId {
 "name": "Lucas Mendes",
 "email": "devsdmf@gmail.com",
 "age": 23
 }
77. WEB API’S FROM SCRATCH PUT FOR UPDATE Full replacement: PUT /customers/existingId {
 "name": "Lucas Mendes",
 "email": "devsdmf@gmail.com",
 "age": 23
 }
78. WEB API’S FROM SCRATCH POST FOR CREATE On a parent resource: POST /customers {
 "name": "Lucas Mendes",
 "email": "devsdmf@gmail.com",
 "age": 23
 } Response: 201 Created
 Location: https://api.tiendanube.com/customers/182
79. WEB API’S FROM SCRATCH POST FOR UPDATE On instance resource: POST /customers/182 {
 "name": "Lucas Mendes",
 "email": "devsdmf@gmail.com",
 "age": 23
 } Response: 200 OK
80. PATCH AND DELETE
81. WEB API’S FROM SCRATCH UPDATE WITH PATCH Send only the changed fields: PATCH /customers/182 {
 "name": "John Doe"
 } Response: 200 OK
82. WEB API’S FROM SCRATCH DELETE A RESOURCE Empty body in request and response: DELETE /customers/182 
 Response: 200 OK
83. BASE URL
84. WEB API’S FROM SCRATCH BASE URL http(s)://api.tiendanube.com vs http(s)://www.tiendanube.com/api/
85. VERSIONING
86. 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
87. RESOURCE FORMAT
88. WEB API’S FROM SCRATCH RESOURCE FORMAT - MEDIA TYPES ▸ Request: Accept header ▸ Response: Content-Type header ▸ application/json ▸ application/json, application/xml ▸ …
89. WEB API’S FROM SCRATCH RESOURCE FORMAT - CAMEL CASE "JS" in "JSON" = JavaScript Wrong: {
 "user_name": "Lucas Mendes"
 } Right: {
 "userName": "Lucas Mendes”
 }
90. WEB API’S FROM SCRATCH RESOURCE FORMAT - DATE/TIME/TIMESTAMP Use ISO-8601 Example: {
 "createdTimestamp": "2017-10-20T21:39:37Z"
 }
91. RESPONSE BODY
92. 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
93. 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
94. 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
95. REFERENCES
96. WEB API’S FROM SCRATCH REFERENCES (LINKING) ▸ Distributed Hypermedia is paramount! ▸ Every accessible Resource has a unique URL. ▸ Replace IDs when possible.
97. 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
 }
98. PAGINATION
99. WEB API’S FROM SCRATCH PAGINATION ▸ Collection Resources must support pagination query parameters ▸ Offset ▸ Limit GET /stores?offset=50&limit=10
100. PARTIAL REPRESENTATION
101. WEB API’S FROM SCRATCH PARTIAL REPRESENTATION ▸ Provide content filtering by using query parameters GET /stores/57432?fields=email,domain
102. ERRORS
103. WEB API’S FROM SCRATCH ERRORS ▸ As descriptive as possible ▸ As much information as possible ▸ Developers are your customers
104. 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"
 }
105. CACHE
106. 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
107. SECURITY
108. 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
109. 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
110. WEB API’S FROM SCRATCH WHY USE API KEYS ? ▸ Limited Exposure ▸ Password reset ▸ Independence ▸ Speed ▸ Traceability
111. 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”
112. LOGGING
113. DOCUMENTATION AND SPECIFICATION
114. 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
115. TIME TO DEMO
116. THANK YOU! Lucas Mendes
 Software Architect at Tienda Nube
 about.me/devsdmf We're hiring, join the crew! 
 bit.ly/work-at-tiendanube