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

Decomposing Service Descriptions: The Future of...

paraskakis
October 22, 2018

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.

paraskakis

October 22, 2018
Tweet

More Decks by paraskakis

Other Decks in Programming

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

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

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

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

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

    generated from code Design-first API Development ❔
  9. 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
  10. #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
  11. #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
  12. #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
  13. 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
  14. • Reuse of existing artifacts - e.g. Supermodel.io • OpenAPI

    Spec 3.0.2 has Components • Upcoming OpenAPI Spec enhancements: • Overlays • Alternate Schemas 1. Modularity
  15. 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
  16. 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!
  17. 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
  18. 5. API Tooling Opportunities • Specialized Tools/Languages for each Layer

    • Tools to Decompose, Organize Layers • Tooling to Recompose Layers • Real Service Documentation & Discovery
  19. 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