Have Your Layer Cake and Eat it Too

Decomposing Service Descriptions & the Future of API Design. Keynote talk at Gluecon 2018.

Transcript

1. Emmanuel Paraskakis @manp Have Your Layer Cake and Eat it Too
2. “Software is Eating the World” - Marc Andreessen, a16z
3. “Fuel for the Next Expansion of Software Eating the World” - Martin Casado, a16z https://a16z.com/2018/03/09/api-world-summit/ APIs & Services are…
4. apiary + 439,438 APIs 4M+ API Consumers 344,404 API Designers
5. How we Built APIs & Services API as a by-product of building apps API documentation generated from code Design-first API Development
6. 2006: API as a By-Product API as a by-product of building apps API documentation generated from code Design-first API Development
7. 2010: API Docs from Code API documentation generated from code Design-first API Development API as a by-product of building apps
8. Developer Experience API as a Product
9. 2014: Design-first API Development Design-first API Development API as a by-product of building apps API documentation generated from code
10. 2018 API as a by-product of building apps API documentation generated from code Design-first API Development ❔
11. openapi: "3.0.1" info: title: Online Store API version: 1.0 … servers: - url: https://staging.example.com/ description: Staging environment … security: - api_key: [] … x-ibm-configuration: enforced: true cors: enabled: true … paths: /customers/{id}/orders: get: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … metadata deployment runtime interface schema
12. #1 API Description Documents are Monolithic openapi: "3.0.1" info: title: Sales Reporting API version: 1.0 … servers: - url: https://qa.example.com/ description: QA environment … security: - api_key: [] … x-ibm-configuration: enforced: false cors: enabled: true … paths: /reports: post: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … openapi: "3.0.1" info: title: Online Store API version: 1.0 … servers: - url: https://staging.example.com/ description: Staging environment … security: - api_key: [] … x-ibm-configuration: enforced: true cors: enabled: true … paths: /customers/{id}/orders: get: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … schema schema
13. #2 Coupling Interface Design with Runtime Configuration openapi: "3.0.1" info: title: Online Store API version: 2.0 … servers: - url: https://staging.example.com/ description: Staging environment … security: - OAuth2: … x-ibm-configuration: enforced: true cors: enabled: true … paths: /customers/{id}/orders: get: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … openapi: "3.0.1" info: title: Online Store API version: 1.0 … servers: - url: https://staging.example.com/ description: Staging environment … security: - api_key: [] … x-ibm-configuration: enforced: true cors: enabled: true … paths: /customers/{id}/orders: get: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … runtime runtime no runtime no runtime
14. #3 Don’t Know where Service will be Deployed in Future openapi: "3.0.1" info: title: Online Store API version: 1.0 … servers: - url: https://prod.example.com/ description: Production environment … security: - api_key: [] … x-ibm-configuration: enforced: true cors: enabled: true … paths: /customers/{id}/orders: get: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … openapi: "3.0.1" info: title: Online Store API version: 1.0 … servers: - url: https://staging.example.com/ description: Staging environment … security: - api_key: [] … x-ibm-configuration: enforced: true cors: enabled: true … paths: /customers/{id}/orders: get: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … deployment deployment no deployment no deployment
15. openapi: "3.0.1" info: title: Online Store API version: 1.0 … servers: - url: https://staging.example.com/ description: Staging environment … security: - api_key: [] … x-ibm-configuration: enforced: true cors: enabled: true … paths: /customers/{id}/orders: get: … content: application/json: schema: $ref: "#/components/schemas/Orders" … components: schemas: Orders: … metadata deployment runtime interface schema metadata deployment runtime interface schema
16. Layered Approach
17. Opportunities
18. 1. Tools, Specific to Each Layer • Evolve New Description Formats
 or • Adopt existing formats
 e.g. Express Gateway YAML • Emerging tools that specialize in each layer
 e.g. Supermodel • New tools to extract env data at deploy time
19. 2. Tools to Decompose, Organize Layers • Enable organizations to separate/manage layers • OAS 3 has built in-modularity - components • Existing efforts but within vendor’s stack:
 Swaggerhub Domains and RAML Datatypes
20. 3. Tooling to Recompose Layers • Complete description of a running service • Source of Truth: Documentation Automated Testing Client Generation Analytics/Monitoring
21. 4. Real Service Documentation • True Developer Experience -
 Use Information in All Layers • Developer Portals for Humans
 Accurate, Personalized Documentation • Discovery for Machines
 Enables Conversational Interfaces
22. API Tooling Opportunities 1. Tools, Specific to Each Layer 2. Tools to Decompose, Organize Layers 3. Tooling to Recompose Layers 4. Real Service Documentation