REST api's

What are REST api's, where do you use it and how do you use it!

Transcript

2. THINGS TO CONSIDER WHEN BUILDING A REST API
3. JEROEN JOOSEN Team Lead - Serverside
4. A P I ’ S
5. W H A T , W H E R E , H O W ?
6. API API = Application Programming Interface Communication tools between different pieces of software/applications More API’s available then you think • Split them up in internal and external API’s • Categories them, for example: web service api’s, library api’s No specific standard, only a set of conventions and constraints
7. T Y P E S O F A P I ’ S
8. SOAP
9. SOAP • WSDL • Function driven • “Do this” principle • Expensive • Not stateless
10. SOAP REST
11. REST • Uniformity • Stateless • “Become this” principle • Caching • Aims to be fast and able to grow easily
12. SOAP REST GRAPHQL
13. GRAPHQL • New kid • Lot’s of freedom • Expensive • Facebook
14. R E S T A P I ’ S
15. H T T P
16. HTTP • HyperText Transfer Protocol • Protocol to talk between HyperMedia (ex internet) • Request - response • Different components • REST uses everything HTTP has to give!
17. URI
18. URI • /thomasmore/hello • Defines the resource you want to talk to • Think in object structure • Collection to singular to collection to singular to… • /users • /users/123 • /users/123/addresses • /users/123/addresses/456 • Can be extended with GET parameters for filtering, paging or searching • /users?search=john • /users?p=1 • /users?email=hello@world.com
19. URI VERBS
20. VERBS • GET, POST, PUT, PATCH, DELETE, COPY,… • Defines the action of the request • Can be categorised in safe, idempotent and normal operations • GET • Retrieve a resource • Safe operation • POST • Create a new resource • Normal operation • PUT • Update an existing resource • Idempotent operation • DELETE • Delete a resource • Idempotent operations
21. URI VERBS BODY
22. BODY • Content of the request or response • Raw, X-Form-URL-Encoded, Form-Data • Use raw body for request and response • JSON • But can also be every other data type (XML, Google’s protobuf, Apache Avro, Thrift, etc) • Consistent in structure
23. URI VERBS BODY HEADERS
24. HEADERS • Functional parameters for request and response • Manipulate request or response • Cookies, Authorization, Accept-Language,… • Custom headers (X-Client-Id, My-Custom-Header) • Use to define parts of the request that are not request specific • Language • Authentication • Content type • … • Gives the client info about the response • Status code • Caching • …
25. URI BODY VERBS HEADERS STATUS CODES
26. STATUS CODES • Tells what the server thinks about your request • Code based • 201 = Created • 200 = OK • 404 = Not Found • 400 = Bad Request • 204 = No content • 422 = Unprocessable Entity • 418 = I’m a teapot
27. L E T ’ S C O M B I N E T H E S E
28. G E T
29. G E T
30. P O S T
31. P O S T
32. P U T
33. P U T
34. D E L E T E
35. D E L E T E
36. M A K E Y O U R A P I T H E B E S T
37. H A T E O A S
38. HATEOAS • Hypermedia As The Engine Of Application State • Level 3 of the Richardson Maturity Level • Creates discoverability • Likes links on a website • Connecting resources to each other • Opportunity to change resources without breaking the client • Chatty application • Lot’s of traffic • No issue with HTTP/2 • Makes caching better!
39. A U T H E N T I C A T I O N
40. AUTHENTICATION • REST = Stateless • Stateless authentication • No session or cookies • Basic authentication • oAuth • JWT tokens • Authentication header
41. V E R S I O N I N G
42. VERSIONING • Prevents the client from breaking • Better to not implement this in the first version • Start using it in second version • Try to work backwards compatible • Header • Custom header • Accept header • URI • /api/v2/users/123
43. E D G E - C A S E S
44. E D G E C A S E S WE CAN’T ALWAYS GET WHAT WE WANT URI’s that can’t be defined in the structure that we want, bodies that are not consistent based on a specific resource, …
45. E D G E C A S E S TRY TO FIND STRUCTURE AND CONSISTENCY Namespacing endpoints • /login, /forgot-password • /auth/login • /auth/forgot-password • /faqcategories, /faqquestions • /faq/categories • /faq/questions
46. E D G E C A S E S TRY TO FIND STRUCTURE AND CONSISTENCY Body structure • Keep base structure • Validate based on resource or add identifier field to body
47. T O O L S
48. POSTMAN
49. POSTMAN RAML OPEN API V3
50. POSTMAN RAML OPEN API V3 INTERNET
51. T O O L S INTERNET http://restcookbook.com/ https://github.com/marmelab/awesome-rest https://zalando.github.io/restful-api-guidelines/ http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way/ https://philsturgeon.uk/ …
52. JEROEN JOOSEN jeroen@novemberfive.co