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.

Transcript

1. 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
2. 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.
3. “Software is Eating the World” - Marc Andreessen, a16z
4. “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…
5. apiary + 470,440 APIs 5.5M+ API Consumers 365,802 API Designers
6. How we Built APIs & Services API as a by-product of building apps API documentation generated from code Design-first API Development
7. 2006: API as a By-Product API as a by-product of building apps API documentation generated from code Design-first API Development
8. 2010: API Docs from Code API documentation generated from code Design-first API Development API as a by-product of building apps
9. Developer Experience API as a Product
10. 2014: Design-first API Development Design-first API Development API as a by-product of building apps API documentation generated from code
11. 2018 API as a by-product of building apps API documentation generated from code Design-first API Development ❔
12. 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
13. #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
14. #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
15. #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
16. 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
17. Future of API Design:
 Layered Approach
18. • Reuse of existing artifacts - e.g. Supermodel.io • OpenAPI Spec 3.0.2 has Components • Upcoming OpenAPI Spec enhancements: • Overlays • Alternate Schemas 1. Modularity
19. 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
20. 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!
21. 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
22. 5. API Tooling Opportunities • Specialized Tools/Languages for each Layer • Tools to Decompose, Organize Layers • Tooling to Recompose Layers • Real Service Documentation & Discovery
23. 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