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.

Specification-driven API Design with OpenAPI

136 views

Published on

This talk, originally given at "bits, bytes & bier #3", shows the importance of API Design and documentation for developer experience (DX), explains the OpenAPI specification format and then explains how a spec-driven API lifecycle can help with DX.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Specification-driven API Design with OpenAPI

  1. 1. Specification-driven API Design with OpenAPI Lukas Rosenstock bits, bytes & bier, 22.11.2018
  2. 2. APIs? DX Developer Experience Open API Spec- driven “Docs Like Code”
  3. 3. APIs? DX Developer Experience Open API Spec- driven API abbr. Application Programming Interface n. A remote interface available over HTTP(S), designed in a REST or RPC style. “Docs Like Code”
  4. 4. APIs? DX Developer Experience Open API Spec- driven Public Partner Private Microservices “Docs Like Code”
  5. 5. APIs? DX Developer Experience Open API Spec- driven “Docs Like Code” Public Partner Private Microservices
  6. 6. APIs? DX Developer Experience Open API Spec- driven API Design Scope Consistency Future-proof “Docs Like Code”
  7. 7. APIs? DX Developer Experience Open API Spec- driven API Design Docs Conceptual Guides / Samples API Reference “Docs Like Code”
  8. 8. APIs? DX Developer Experience Open API Spec- driven Spec machine- readable “Docs Like Code”
  9. 9. Metadata openapi: 3.0.0 info: title: ipify version: v1 description: A Simple IP Address API servers: - url: 'https://api.ipify.org/'
  10. 10. Paths paths: /: get: summary: Get client IP parameters: - in: query name: format description: 'The format to return the response in, i.e. json.' schema: type: string default: json responses:
  11. 11. Responses / JSON Schemas responses: '200': description: Success response content: application/json: schema: type: object properties: ip: type: string example: 88.68.10.107
  12. 12. Request with References (OpenAPI 2.0)
  13. 13. APIs? DX Developer Experience Open API Spec- driven Spec machine- readable Docs Reference  Manual Writing Auto- Generation Code Implementation “Docs Like Code”
  14. 14. ReDoc
  15. 15. Swagger UI
  16. 16. APIs? DX Developer Experience Open API Spec- driven “Docs Like Code”
  17. 17. APIs? DX Developer Experience Open API Spec- driven API Design “Docs Like Code”
  18. 18. APIs? DX Developer Experience Open API Spec- driven Spec machine- readable Manual Writing Visual Tools API Design “Docs Like Code”
  19. 19. stoplight.io
  20. 20. APIs? DX Developer Experience Open API Spec- driven Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  “Docs Like Code”
  21. 21. APIs? DX Developer Experience Open API Spec- driven Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Client SDKs Server Stubs Mock Servers“Docs Like Code”
  22. 22. APIs? DX Developer Experience Open API Spec- driven Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Tests “Docs Like Code” Code = Spec ?
  23. 23. APIs? DX Developer Experience Open API Spec- driven Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Tests Single Source Of Truth “Docs Like Code”
  24. 24. APIs? DX Developer Experience Open API Spec- driven API Design Docs Conceptual Guides / Samples API Reference “Docs Like Code”
  25. 25. APIs? DX Developer Experience Open API Spec- driven “Docs Like Code” Use developer toolchain for writing Markdown
  26. 26. APIs? DX Developer Experience Open API Spec- driven “Docs Like Code”
  27. 27. APIs? DX Developer Experience Open API Spec- driven “Docs Like Code”

×