Share
Embed
Have Your Layer Cake and Eat it Too
Decomposing Service Descriptions & the Future of API Design. Keynote talk at Gluecon 2018.
Emmanuel Paraskakis
May 17, 2018
Transcript
22 slides
-
“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… -
How we Built APIs & Services API as a by-product
of building apps API documentation generated from code Design-first API Development -
2006: API as a By-Product API as a by-product of
building apps API documentation generated from code Design-first API Development -
2010: API Docs from Code API documentation generated from code
Design-first API Development API as a by-product of building apps -
2014: Design-first API Development Design-first API Development API as a
by-product of building apps API documentation generated from code -
2018 API as a by-product of building apps API documentation
generated from code Design-first API Development ❔ -
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 -
#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 -
#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 -
#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 -
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 -
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 -
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 -
3. Tooling to Recompose Layers • Complete description of a
running service • Source of Truth: Documentation Automated Testing Client Generation Analytics/Monitoring -
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 -
API Tooling Opportunities 1. Tools, Specific to Each Layer 2.
Tools to Decompose, Organize Layers 3. Tooling to Recompose Layers 4. Real Service Documentation