RESTful APIS - Let your apps talk to each other

Do you know the right way and correct techniques to develop a good scalable RESTful API? This talk covers the misconceptions and the pragmatism around this architectural style, highlighting some important concepts to make your API achieve two important points: adoption and scalability.

Transcript

1. RESTFUL APIS LET YOUR APPS TALK TO EACH OTHER Lucas Mendes (@devsdmf) Lead Backend Engineer, ISET www.iset.com.br
2. ABOUT ME code writer, software architect, open source lover, musician and writer in free hours. MIM ACHER devsdmf@gmail.com www.devsdmf.io github.com/devsdmf about.me/devsdmf twitter.com/devsdmf
3. THINGS YOU SHOULD KNOW!
4. COMPUTER NETWORK A computer network or data network is a telecommunications network which allows nodes to share resources. [...] The best-known computer network is the Internet.
5. THE OSI MODEL The Open Systems Interconnection model (OSI model) is a conceptual model that characterizes and standardizes the communication functions of a telecommunication or computing system without regard to their underlying internal structure and technology.
6. OSI MODEL LAYERS
7. TCP/IP The Internet protocol suite is the conceptual model and set of communications protocols used on the Internet and similar computer networks.
8. THE HTTP PROTOCOL The Hypertext Transfer Protocol (HTTP) is an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web. The HTTP is designed to enable communications between clients and servers and works as a request-response protocol between a client and server.
9. HTTP FLOW
10. HTTP METHODS GET, POST, PUT, DELETE, HEAD, OPTIONS, CONNECT...
11. HTTP STATUS CODES 1xx: Information 2xx: Successful 3xx: Redirection 4xx: Client Error 5xx: Server Error 100 Continue 200 OK 301 Moved Permanently 400 Bad Request 500 Internal Server Error 101 Switching Protocols 201 Created 302 Found 401 Unauthorized 502 Bad Gateway
12. HTTP STATUS CODES 1xx: Information 2xx: Successful 3xx: Redirection 4xx: Client Error 5xx: Server Error 103 Checkpoint 204 No Content 304 Not Modified 403 Forbidden 503 Service Unavailable 205 Reset Content 404 Not Found 504 Gateway Timeout
13. APIS
14. WHAT IS API?
15. DEVELOPERS AS CUSTOMERS
16. REST
17. WHAT IS REST? Representational state transfer (REST) or RESTful web services are one way of providing interoperability between computer systems on the Internet.
18. WHAT IS A RESTFUL API?
19. ABOUT A RESTLESS API?
20. WHY REST?
21. JSON
22. WHAT IS JSON?
23. JSON DOCUMENT { "title": "RESTful APIs", "subtitle": "Let your apps talk to each other", "presenter": { "name": "Lucas Mendes", "email": "devsdmf@gmail.com" }, "tags": ["rest","api"] }
24. HATEOAS Hypermidia As The Engine Of Application State
25. API DESIGN
26. EXAMPLE DOMAIN: PAYMENT API Customer Order Payment Transaction and more...
27. REST FUNDAMENTALS
28. RESOURCES NOUNS, NOT VERBS ARCHITECTURAL STYLE FOR USE-CASE SCALABILITY
29. RESOURCES WE HAVE TWO KIND OF RESOURCES: Collection Resources Instance Resources
30. AND ABOUT? /getCustomer /createOrder /updateTransaction /verifyAccountEmailAddress
31. DON'T DO THIS!
32. KEEP IT SIMPLE
33. COLLECTION RESOURCE /CUSTOMERS
34. INSTANCE RESOURCE /CUSTOMERS/123
35. BEHAVIOR GET PUT POST DELETE HEAD
36. GETTING A RESOURCE GET /CUSTOMERS/123 { "name": "Lucas Mendes", "email": "devsdmf@gmail.com", "orders": [ { "href": "https://api.payment.com/orders/456" } ], "accountStatus": "active" }
37. CREATING A RESOURCE POST /CUSTOMERS { "name": "Lucas Mendes", "email": "devsdmf@gmail.com" }
38. UPDATING A RESOURCE PUT /CUSTOMERS { "email": "newemail@domain.com" }
39. DELETING A RESOURCE DELETE /CUSTOMERS/123
40. BASE URL HTTPS://API.PAYMENTS.COM VS HTTPS://WWW.PAYMENTS.COM/API/REST
41. VERSIONING URL HTTPS://API.PAYMENTS.COM/V1 VS MEDIA-TYPE APPLICATION/FOO+JSON;APPLICATION&V=1
42. RESOURCE FORMAT
43. MEDIA TYPE CONTENT-TYPE: APPLICATION/JSON WHEN TIME ALLOWS: APPLICATION/FOO+JSON APPLICATION/FOO+JSON;BAR=BAZ&V=1
44. CAMELCASE 'JS' IN 'JSON' = JAVASCRIPT WRONG: RIGHT: { "user_name": "Lucas Mendes" } { "userName": "Lucas Mendes" }
45. DATE/TIME/TIMESTAMP USE ISO-8601 EXAMPLE: { "createdTimestamp": "2016-12-15T:09:02:24.343Z" }
46. RETURN VALUES
47. RESPONSE BODY GET OBVIOUS WHAT ABOUT POST? RETURN THE REPRESENTATION IN THE RESPONSE WHEN FEASIBLE ADD OVERRIDE (?_BODY=FALSE) FOR CONTROL
48. HEADER GET /CUSTOMERS/123 ACCEPT: APPLICATION/JSON, TEXT/PLAIN Accept header Header values comman delimited in order of preference
49. REFERENCES (LINKING)
50. HREF Distributed Hypermedia is paramount! Every acessible Resource has a canonical unique URL
51. INSTANCE WITH HREF GET /CUSTOMERS/123 { "name": "Lucas Mendes", "email": "devsdmf@gmail.com", "orders": [ { "href": "https://api.payment.com/orders/456" } ], "accountStatus": "active" }
52. PAGINATION
53. LIMITING RESULTS COLLECTION RESOURCES MUST SUPPORT QUERY PARAMS: GET /CUSTOMERS?OFFSET=50&LIMIT=25 offset limit
54. QUERY PARAMETERS
55. FILTERING RESULTS GET /CUSTOMERS/123?FIELDS=NAME,EMAIL { "name": "Lucas Mendes", "email": "devsdmf@gmail.com" }
56. ERRORS
57. ERRORS As descriptive as possible As much information as possible Developers are your customers
58. ERROR RESPONSE POST /CUSTOMERS 400 BAD REQUEST { "status": 400, "code": "12345", "property": "email", "message": "The specified email address is already taken", "moreInfo": "https://www.payments.com/docs/api/errors/12345" }
59. CACHING
60. CACHING RESOURCES Use HTTP cache Use cache servers for increase the performance Return a 304 Not Modified when the resource is cached
61. SECURITY
62. SECURITY GUIDELINES Avoid sessions when possible: Authenticate every request if necessary Stateless Authorize based on resource content, NOT URL! Use Existing Protocol: OAuth 1.0a, OAuth 2.0, Basic over SSL only Custom Authentication Scheme: Only if you provide client code / SDK Only if you really, really know what are you doing Use API Keys instead of Username/Passwords
63. 401 VS 403 401 "Unauthorized" really means Unauthenticated "You need valid credentials for me to response to this request" 403 "Forbidden" really means Unauthorized "I understood your credentials, but so sorry, you're not allowed!"
64. API KEYS Limited Exposure Password Reset Independence Speed Traceability
65. DOCUMENTATION AND SPECIFICATION
66. SDK
67. WHAT IS AN SDK?
68. HOW TO DEVELOP A GOOD SDK?
69. STATE OF THE ART “State of the art (sometimes cutting edge) refers to the highest level of general development, as of a device, technique, or scientific field achieved at a particular time. It also refers to such a level of development reached at any particular time as a result of the common methodologies employed at the time.”
70. THANK YOU! http://bit.ly/devsdmf-restful