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.

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: support@example.com
    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