$30 off During Our Annual Pro Sale. View Details »

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. Schema-First API Design
    with OpenAPI / Swagger
    Yos Riady
    yos.io
    bit.ly/2uDyaSN

    View Slide

  2. API Design process
    What is OpenAPI?
    Introduction Design Spec Tools Conclusion
    Writing OpenAPI specs
    Summary and further
    learning
    Tooling around
    OpenAPI

    View Slide

  3. You’re building an API

    View Slide

  4. ● 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

    View Slide

  5. Is there a better way to do this?

    View Slide

  6. 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.

    View Slide

  7. 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.

    View Slide

  8. API Specification Languages

    View Slide

  9. API Design process
    What is OpenAPI?
    Introduction Design Spec Tools Conclusion
    Writing OpenAPI specs
    Summary and further
    learning
    Tooling around
    OpenAPI

    View Slide

  10. OpenAPI / Swagger

    View Slide

  11. 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

    View Slide

  12. 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

    View Slide

  13. editor.swagger.io

    View Slide

  14. Writing an OpenAPI Specification: openapi
    openapi: 3.0.0 The semantic version number of the
    OpenAPI Specification version that
    the OpenAPI document uses.

    View Slide

  15. 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

    View Slide

  16. 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:
    /orders:
    post:

    View Slide

  17. 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.

    View Slide

  18. 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'

    View Slide

  19. editor.swagger.io

    View Slide

  20. 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.

    View Slide

  21. View Slide

  22. API Design process
    What is OpenAPI?
    Introduction Design Spec Tools Conclusion
    Writing OpenAPI specs
    Summary and further
    learning
    Tooling around
    OpenAPI

    View Slide

  23. Schema-First API Design
    with OpenAPI / Swagger
    Yos Riady
    yos.io
    bit.ly/2uDyaSN

    View Slide

  24. Q&A

    View Slide