Share
Embed
Decomposing Service Descriptions: The Future of API Design
How to make your API Descriptions DRY and reusable. By layering different sections you get modularity so you can simplify your service deployments.
Emmanuel Paraskakis
October 22, 2018
Transcript
23 slides
-
Copyright © 2018, Oracle and/or its affiliates. All rights reserved.
| Confidential – Oracle Internal/Restricted/Highly Restricted Decomposing Service Descriptions The Future of API Design Emmanuel Paraskakis Sr. Director of Product Management Oracle API Platform @manp -
Safe Harbor Statement The following is intended to outline our
general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, timing, and pricing of any features or functionality described for Oracle’s products may change and remains at the sole discretion of Oracle Corporation. -
“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 -
• Reuse of existing artifacts - e.g. Supermodel.io • OpenAPI
Spec 3.0.2 has Components • Upcoming OpenAPI Spec enhancements: • Overlays • Alternate Schemas 1. Modularity -
2. Separation of Concerns • Focus by expertise or role,
e.g: • Domain Experts for Data Structures • Architects for Interface Design • DevOps for Runtime Configuration • Automation for Deployment & Metadata layers -
3. Defer Implementation Decisions • Focus on the problem at
hand • “Uncle” Bob Martin: Clean Architecture • Our industry needs a standard to describe runtime configuration: Similar to Express Gateway or Ambassador (in OAS?) • Not extensions! They are different for every vendor • Having a “runtime” description language means you can check-in, diff, test! -
4. Real Service Discovery • Developer Portals for Humans Accurate,
Personalized Documentation • Discovery for Machines Enables Conversational Interfaces • Our industry needs a standard for Metadata - apis.json? GENERIC API DOCUMENTATION -
5. API Tooling Opportunities • Specialized Tools/Languages for each Layer
• Tools to Decompose, Organize Layers • Tooling to Recompose Layers • Real Service Documentation & Discovery -
Copyright © 2018, Oracle and/or its affiliates. All rights reserved.
| Confidential – Oracle Internal/Restricted/Highly Restricted Thank you! @manp 23 Tuesday • Code One: Bring Design Thinking to Your API Lifecycle [DEV6970] - Jakub, Emmanuel • OOW: Design, Create and Manage APIs for the Digital Economy [HOL6281] - Robert, Kiran, Emmanuel Wednesday • Code One: Client-Driven APIs [DEV6276] - Mark • Code One: Accelerate your Development with Design-First API Management [HOL6945] - Robert, Jakub, Kiran, Emmanuel Thursday • OOW: The future of API Management with Oracle API Platform & Apiary [PRM6971] - Robert, Jakub, Emmanuel • OOW: How Rabobank Is Using Oracle API Platform to Achieve API Success [CAS4501] - Robert