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

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

You’re building an API 

● 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 

Is there a better way to do this? 

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. 

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. 

API Specification Languages 

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

OpenAPI / Swagger 

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 

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 

editor.swagger.io 

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

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 

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: 

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. 

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' 

editor.swagger.io 

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. 

No content

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

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

Q&A