Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

APIDays - API Design Workshop


Published on

How to get from the initial API project idea to an API contract and its published documentation?

Published in: Technology
  • Be the first to comment

APIDays - API Design Workshop

  1. 1. Workshop Learn How To Design and Document an API with
  2. 2. Workshop takeaways How to get from the initial API project idea... an API contract and its published documentation
  3. 3. Who are we? Jonathan @j_michaux product manager @ Restlet Antoine @richard_antoine product manager @ Restlet
  4. 4. Restlet Helping agile teams deliver API projects
  5. 5. Workshop steps 1. Things to think about before you start 2. Create your API contract 3. Document and share your API
  6. 6. API Design What to think about before you start crafting your API contract
  7. 7. ● Is the API worth building? ● What problem does the API solve? ● How will the API be used? ● What API project methodology will we use? API Design checklist
  8. 8. Is the API worth building?
  9. 9. What problem does the API solve? People want to do car sharing We offer a car sharing service Developers want to integrate it into their apps
  10. 10. Ride Sharing API
  12. 12. Screenshot from BlaBlaCar
  13. 13. What API project methodology to use?
  14. 14. API Contract
  15. 15. Restlet Studio: API Design made easy
  16. 16. Steps 1. resources 2. operations 3. responses RFC 2616 (june 1999)
  17. 17. Identify resources What’s a resource? “A network data object or service that can be identified by a URI [...]. Resources may be available in multiple representations (e.g. multiple languages, data formats, size, and resolutions) or vary in other ways.” RFC 2616 (june 1999)
  18. 18. What’s a resource? Second attempt! Identify resources “A resource is anything that’s important enough to be referenced as a thing in itself.” Leonard Richardson & Sam Ruby - “Restful Webservices”
  19. 19. Define operations “Actions that can be performed on your resources. The most common operations are GET, POST, PUT, PATCH and DELETE.” What’s an operation?
  20. 20. /rides - GET - POST /rides/{id} - GET - PUT - DELETE
  21. 21. Define responses ● Status code ● Representation
  22. 22. Define responses: HTTP status codes 1xx Hold on 2xx Here you go 3xx Go away 4xx You f**ked up 5xx I f**ked up
  23. 23. Define representation ● Data structure ● Formats
  24. 24. Define representation: formats JSON XML YAML JPG SVG CSV TEXT PDF MPEG ZIP
  25. 25. Iterate on API Design
  26. 26. Document your API
  27. 27. Prepare documentation ● Add general information: endpoints, security, a picture ● Structure your API via sections ● Complete documentation with additional information on error handling and authentication
  28. 28. Publish your documentation
  29. 29. Move forward in your API project
  30. 30. Next steps ● Share your API design and get feedback on it ● Use Client SDK to speed up mobile app development ● Bootstrap your server code with Server Skeletons ● Export a Swagger file if you need to
  31. 31. Thanks for watching! Thanks for participating! Try and send us feedback!