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
2. API Design process What is OpenAPI? Introduction Design Spec Tools Conclusion Writing OpenAPI specs Summary and further learning Tooling around OpenAPI
3. You’re building an API
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
5. Is there a better way to do this?
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.
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.
8. API Specification Languages
9. API Design process What is OpenAPI? Introduction Design Spec Tools Conclusion Writing OpenAPI specs Summary and further learning Tooling around OpenAPI
10. OpenAPI / Swagger
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
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
13. editor.swagger.io
14. Writing an OpenAPI Specification: openapi openapi: 3.0.0 The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.
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
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: <operation> /orders: post: <operation>
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.
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'
19. editor.swagger.io
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.
22. API Design process What is OpenAPI? Introduction Design Spec Tools Conclusion Writing OpenAPI specs Summary and further learning Tooling around OpenAPI
23. Schema-First API Design with OpenAPI / Swagger Yos Riady yos.io bit.ly/2uDyaSN
24. Q&A