Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.

Get some REST - a discussion on good API design

297 visualizaciones

Publicado el

APIs are the cornerstone of Digital systems and platforms today. APIs find their use in several architecture patterns - be it SOA & Microservices or even modern UI apps. While being interactive, this talk would look closely into aspects of API design, which we tend to ignore or abuse frequently. This talk would also draw some perspectives on modern architectures like Serverless & GraphQL, and how we could employ new & powerful API patterns in our applications and systems.

Key Takeaways
=> As developers and architects, you should walk away with some guidelines and best practices on API design
=> The talk would give a broad direction of the future of APIs and how future systems can be architected with new patterns

Publicado en: Software
  • Sé el primero en comentar

Get some REST - a discussion on good API design

  1. 1. GET SOME REST PRINCIPLES OF GOOD API DESIGN MANOJ GANAPATHI, CHIEF ARCHITECT, CODEOPS
  2. 2. ABOUT ME Manoj Ganapathi Chief Architect, CodeOps Technologies • More than 18+ years of IT experience • Seasoned Architect with products and services experience • Specialized in Cloud and DevOps @manojgr manojgr@gmail.com, manoj@codeops.tech https://www.linkedin.com/in/manojg
  3. 3. AGENDA • ABOUT APIS & REST • API DESIGN BEST PRACTICES • APIS IN THE SERVERLESS WORLD • THE FUTURE – GRAPHQL
  4. 4. ABOUT APIS
  5. 5. WHY ARE APIS IMPORTANT? • KEY FOR PLATFORMS – HELP SHAPE ECOSYSTEMS • API DESIGN INFLUENCES APP EXPERIENCES • APIS ARE FOR DEVELOPERS. THEY INFLUENCE DEVELOPER PRODUCTIVITY • APIS ARE A GATEWAY TO CLOUD-NATIVE ARCHITECTURES
  6. 6. MISCONCEPTIONS? •A FAÇADE/LAYER TO BUSINESS LOGIC •INTERNAL AND EXTERNAL APIS HAVE DIFFERENT IMPORTANCE
  7. 7. WHAT IS REST? • REPRESENTATIONAL STATE TRANSFER (REST) IS AN SOFTWARE ARCHITECTURAL STYLE THAT DEFINES A SET OF CONSTRAINTS TO BE USED FOR CREATING WEB SERVICES. • WEB SERVICES THAT CONFORM TO THE REST ARCHITECTURAL STYLE, TERMED RESTFUL WEB SERVICES, PROVIDE INTEROPERABILITY BETWEEN COMPUTER SYSTEMS ON THE INTERNET. • RESTFUL WEB SERVICES ALLOW THE REQUESTING SYSTEMS TO ACCESS AND MANIPULATE TEXTUAL REPRESENTATIONS OF WEB RESOURCES BY USING A UNIFORM AND PREDEFINED SET OF STATELESS OPERATIONS -FROM WIKIPEDIA
  8. 8. REST BASICS KEY ARCHITECTURAL PROPERTIES • PERFORMANCE • SCALABILITY • SIMPLICITY • MODIFIABILITY • VISIBILITY • PORTABILITY ARCHITECTURAL CONSTRAINTS • CLIENT-SERVER • STATELESS • CACHEABLE • LAYERED SYSTEM • UNIFORM INTERFACE A far cry from the dark ages of SOAP, CORBA, RPC etc!
  9. 9. REST – UNIFORM INTERFACE • IDENTIFICATION OF RESOURCES • MANIPULATION OF RESOURCES THROUGH REPRESENTATION • SELF-DESCRIPTIVE MESSAGES Resource as URIs https://api.co/v1/orders/1 JSON, XML HTTP GET, POST, PUT, DELETE Mediatypes, cacheability, etc.
  10. 10. BEST PRACTICES
  11. 11. GENERAL BEST PRACTICES • PREFER NOUNS TO VERBS • /TICKETS/123 INSTEAD OF /GETTICKET/123 • VERBS CAN BE USED FOR ACTIONS /BOOKS/1/MARKASFAVORITE, /LOGIN • PREFER PLURALS /ORDERS, /CARS ETC. • API PARAMETERS: • PATH - REQUIRED, RESOURCE IDENTIFIER • QUERY – OPTIONAL, QUERY COLLECTIONS • BODY – RESOURCE-SPECIFIC LOGIC • HEADER – GLOBAL, PLATFORM-WIDE
  12. 12. HTTP STATUS CODES ARE YOUR FRIENDS • 1XX: HOLD-ON • 2XX: HERE YOU GO • 3XX: GO AWAY • 4XX: YOU SCREWED UP • 5XX: I SCREWED UP • LEVERAGE ALL STATUS CODES ALONG WITH RELEVANT HEADERS TO COMMUNICATE INTENT CLEARLY • RETURNING 200 FOR ALL CONDITIONS IS A BAD PRACTICE
  13. 13. 2XX – HERE YOU GO! Code Use Example 201 Created Specify a location header pointing to the location of newly created resource POST /Orders … HTTP/1.1 201 Created Location: https://eshop.co/v2/orders/1 202 Accepted Use: Request accepted but will be handled asynchronously. No payload returned POST /jobs HTTP/1.1 202 Accepted 204 No Content The resource was deleted and no payload is returned DELETE /orders/654 HTTP/1.1 204 No content 206 Partial Content A partial list of resources is returned, using pagination, add a Link header to facilitate navigation GET /orders?page=4 HTTP/1.1 206 Partial content Link: <http://eshop.co/orders?page=1>;rel="first ", <http://eshop.co/orders?page=3>;rel="pre v,<http://eshop.co/orders?page=5>;rel="ne xt, <http://eshop.co/orders?page=9>; rel="last"
  14. 14. OTHER CODES Code Use 301 Moved permanently 302 Found 303 See other 304 Not modified (used in caching) 307 Temporary Redirect 308 Permanent Redirect Code Use 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 405 Method not allowed 429 Too many requests Code Use 500 Internal Server Error 501 Not Implemented 503 Service Unavailable 509 Bandwidth Limit exceeded 405 Method not allowed 429 Too many requests
  15. 15. ERROR HANDLING (1/2) • THEREFORE, APIS MUST RETURN A JSON ERROR REPRESENTATION THAT CONFORMS TO THE ERROR.JSON
  16. 16. ERROR HANDLING (2/2) Refer Error.json in the API Spec
  17. 17. VERSIONING • MOST FREQUENT, IN THE URL: HTTPS: //API. COM/V2/RESTAURANTS/1234 • CUSTOM HEADER: X-API-VERSION: 2 • LESS FREQUENT, WITH AN ACCEPT HEADER. CLIENTS DON’T HAVE TO CHANGE ENDPOINT, BUT UPDATE HEADERS GET /RESTAURANTS ACCEPT: APPLICATION/VND.RESTAURANTS.V2+JSON
  18. 18. APIS IN THE SERVERLESS WORLD
  19. 19. TRADITIONAL ARCHITECTURE
  20. 20. MOVING TOWARDS RESILIENCE
  21. 21. GRAPHQL IN A NUTSHELL • A QUERY LANGUAGE FOR YOUR API • QUERY OR MUTATE EXACTLY WHAT YOU WANT • MULTIPLE RESOURCES IN ONE REQUEST • SUBSCRIPTION MODEL • GRAPHQL APIS ARE ORGANIZED IN TERMS OF TYPES AND FIELDS, NOT ENDPOINTS. • ACCESS THE FULL CAPABILITIES OF YOUR DATA FROM A SINGLE ENDPOINT (USUALLY).
  22. 22. Source: Hasura (https://www.slideshare.net/AWSUsersGroupBengalu/architecture-of-scalable- and-resilient-apps-with-graphql-amazon-rds-and-aws-lambda )
  23. 23. ONE OF THE GRAPHQL IMPLEMENTATIONS - HASURA
  24. 24. QUESTIONS?
  25. 25. REFERENCES • HTTPS://WWW.SLIDESHARE.NET/AWSUSERSGROUPBENGALU/ARCHITECTURE-OF-SCALABLE-AND- RESILIENT-APPS-WITH-GRAPHQL-AMAZON-RDS-AND-AWS-LAMBDA • THE NEVER-ENDING REST API DESIGN DEBATE • HTTP://WWW.VINAYSAHNI.COM/BEST-PRACTICES-FOR-A-PRAGMATIC-RESTFUL-API • HTTPS://GITHUB.COM/PAYPAL/API-STANDARDS/BLOB/MASTER/API-STYLE-GUIDE.MD • HTTP://BLOG.OCTO.COM/EN/DESIGN-A-REST-API/ • HTTPS://GITHUB.COM/INTERAGENT/HTTP-API-DESIGN/BLOB/MASTER/SUMMARY.MD • HTTP://SOOKOCHEFF.COM/POST/API/ON-CHOOSING-A-HYPERMEDIA-FORMAT/ • HTTP://WWW.TROYHUNT.COM/2014/02/YOUR-API-VERSIONING-IS-WRONG-WHICH-IS.HTML

×