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

Schema-First API Design

Schema-First API Design

The Schema-first API design approach advocates for writing your API definition first in one of many API Specification languages before writing any code. This talk introduces you to the realm of Schema-First API design and how to get started with the OpenAPI ecosystem.

Yos Riady

April 01, 2018
Tweet

More Decks by Yos Riady

Other Decks in Programming

Transcript

  1. API Design process What is OpenAPI? Introduction Design Spec Tools

    Conclusion Writing OpenAPI specs Summary and further learning Tooling around OpenAPI
  2. • You need to: ◦ Update the server implementation to

    support the new feature. ◦ Update all client libraries / SDKs. ◦ Update the documentation. • All the above must be consistent with each other. • Also, frontend teams are blocked until your backend API is complete. Adding a new feature to the API
  3. Schema-First API Design The Schema-first API design approach means writing

    your API definition first in one of many API Specification languages before writing any code.
  4. Iterate faster in teams Benefits of the Schema-First Approach Generate

    Artifacts Generate API Tests You can generate mock services for clients to work with, even before backend components are ready. Your API Specification can be used to generate functional tests for the API. Your API Specification can be used to generate SDKs, documentation, and server scaffolds.
  5. API Design process What is OpenAPI? Introduction Design Spec Tools

    Conclusion Writing OpenAPI specs Summary and further learning Tooling around OpenAPI
  6. What’s in an OpenAPI Specification? • General information about the

    API • Available paths e.g. /resources ◦ Available operations on each path e.g. GET /resources/{id} ◦ input & output for each operation
  7. openapi: 3.0.0 info: title: Sample API description: Optional multiline or

    single-line description version: 0.1.9 paths: /users: get: summary: Returns a list of users. description: Optional extended description in CommonMark or HTML. responses: '200': # status code description: A JSON array of user names content: application/json: schema: type: array items: type: string
  8. Writing an OpenAPI Specification: openapi openapi: 3.0.0 The semantic version

    number of the OpenAPI Specification version that the OpenAPI document uses.
  9. The info section provides general information about the API. info:

    title: Sample Pet Store App version: 1.0.1 description: This is a sample server for a pet store. termsOfService: http://example.com/terms/ contact: name: API Support url: http://www.example.com/support email: [email protected] license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html Writing an OpenAPI Specification: info
  10. Writing an OpenAPI Specification: paths The paths section contains the

    endpoints such as /products and operations are the HTTP methods such as GET, POST, DELETE paths: /products/{id}: get: <operation> /orders: post: <operation>
  11. paths: /products/{id}: get: operationId: getProductById parameters: - name: id in:

    path description: Product ID required: true schema: type: integer format: int64 responses: '200': content: application/json: schema: $ref: '#/components/schemas/Product' Writing an OpenAPI Specification: paths Each operation documents any parameters for the operation, the different kinds of responses, and other metadata.
  12. Writing an OpenAPI Specification: components components: schemas: # Schema object

    definition Pet: type: object properties: name: type: string petType: type: string required: - name - petType The components section lets you define common data structures used in your API. They can be referenced via $ref whenever a schema is required: $ref: '#/components/schemas/Pet'
  13. And more! There are tons of libraries and frameworks that

    support the OpenAPI ecosystem. Swagger Codegen Generates server stubs and client libraries in over 40 languages / platforms. Tooling around OpenAPI Swagger UI Generate interactive API documentation that lets users try out API calls in the browser.
  14. API Design process What is OpenAPI? Introduction Design Spec Tools

    Conclusion Writing OpenAPI specs Summary and further learning Tooling around OpenAPI
  15. Q&A