Schema-First API Design
2 likes•554 views
The document discusses schema-first API design using OpenAPI/Swagger, emphasizing the importance of writing an API definition before coding. It highlights the benefits of this approach, including faster iteration, generation of API tests, documentation, and SDKs. The document also provides details on writing OpenAPI specifications, including the structure and components of such specifications.
Schema-First API Design
- 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 ArtifactsGenerate 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.
- 9. API Design process What is OpenAPI? Introduction Design Spec Tools Conclusion Writing OpenAPI specs Summary and further learning Tooling around OpenAPI
- 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
- 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: [email protected] 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'
- 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