Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Have Your Layer Cake and Eat it Too

Have Your Layer Cake and Eat it Too

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

paraskakis

May 17, 2018
Tweet

More Decks by paraskakis

Other Decks in Programming

Transcript

  1. “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…
  2. How we Built APIs & Services API as a by-product

    of building apps API documentation generated from code Design-first API Development
  3. 2006: API as a By-Product API as a by-product of

    building apps API documentation generated from code Design-first API Development
  4. 2010: API Docs from Code API documentation generated from code

    Design-first API Development API as a by-product of building apps
  5. 2014: Design-first API Development Design-first API Development API as a

    by-product of building apps API documentation generated from code
  6. 2018 API as a by-product of building apps API documentation

    generated from code Design-first API Development ❔
  7. 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
  8. #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
  9. #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
  10. #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
  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 metadata deployment runtime interface schema
  12. 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
  13. 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
  14. 3. Tooling to Recompose Layers • Complete description of a

    running service • Source of Truth: Documentation Automated Testing Client Generation Analytics/Monitoring
  15. 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
  16. API Tooling Opportunities 1. Tools, Specific to Each Layer 2.

    Tools to Decompose, Organize Layers 3. Tooling to Recompose Layers 4. Real Service Documentation