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 vs Technical Writers

193 views

Published on

This talk, originally given at tcworld18, shows the importance of API Design and documentation for developer experience (DX), introduces OpenAPI and then explains how a spec-driven API lifecycle can help with DX, highlighting the role of technical writers.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Specification-driven API Design vs Technical Writers

  1. 1. Specification-driven API Design vs. Technical Writers Lukas Rosenstock tcworld18, 15th Nov 2018
  2. 2. APIs? DX Developer Experience Open API Spec- driven Tech Writers  “Docs Like Code”
  3. 3. APIs? DX Developer Experience Open API Spec- driven Tech Writers 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 Tech Writers Public Partner Private Microservices “Docs Like Code”
  5. 5. APIs? DX Developer Experience Open API Spec- driven Tech Writers “Docs Like Code” Public Partner Private Microservices
  6. 6. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design Scope Consistency Future-proof “Docs Like Code”
  7. 7. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design Docs Conceptual Guides / Samples API Reference “Docs Like Code”
  8. 8. APIs? DX Developer Experience Open API Spec- driven Tech Writers 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. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Docs Reference  Manual Writing Auto- Generation Code Implementation “Docs Like Code”
  13. 13. ReDoc
  14. 14. Swagger UI
  15. 15. APIs? DX Developer Experience Open API Spec- driven Tech Writers “Docs Like Code”
  16. 16. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design “Docs Like Code”
  17. 17. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design “Docs Like Code”
  18. 18. stoplight.io
  19. 19. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  “Docs Like Code”
  20. 20. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Client SDKs Server Stubs Mock Servers“Docs Like Code”
  21. 21. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Code = Spec ? Tests “Docs Like Code”
  22. 22. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Tests Single Source Of Truth “Docs Like Code”
  23. 23. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design “Docs Like Code”
  24. 24. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design Docs Conceptual Guides / Samples API Reference “Docs Like Code”
  25. 25. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design Docs Conceptual Guides / Samples API Reference Review “The Good Stuff” “Docs Like Code”
  26. 26. APIs? DX Developer Experience Open API Spec- driven Tech Writers Not jobless! More technical “Docs Like Code”
  27. 27. APIs? DX Developer Experience Open API Spec- driven Tech Writers “Docs Like Code” Use developer toolchain for writing Markdown
  28. 28. APIs? DX Developer Experience Open API Spec- driven Tech Writers “Docs Like Code”
  29. 29. APIs? DX Developer Experience Open API Spec- driven Tech Writers “Docs Like Code” 

×