Design-First_API_Development.pdf

Deck for Singapore Laravel Meetup on 22 Dec 2022.

The Design-First API development advocates for designing the API’s contract first before writing any code. The API contract can act as the central draft that keeps all your team members aligned on what your API’s objectives are, and how your API’s resources are exposed. Spotting issues in the design, before writing any code is a much more efficient and streamlined approach, than doing so after the implementation is already in place. This talk would cover an overview of OpenAPI, how to design API contract with Stoplight Studio, as well as asserting API responses against the API contract in testing.

Transcript

2. Ryuta Hamasaki @avosalmon
3. Agenda • Design-First API Development • Overview of OpenAPI • Designing API contract • Running mock server • Validating API response in testing
4. Design-First API Development • Design API contract first • Find and solve problems early on before building API • FE implements the feature using the mock API 👉 No need to wait until API is built • BE implements the API based on the API contract 👉 Validate API response in testing
5. Overview of OpenAPI • Documentation for REST API written in YAML or JSON • Previously known as Swagger • Swagger specification was donated to the OpenAPI Initiative • Swagger = tools to implement OpenAPI specification
6. Designing API Contract
10. Rendering OpenAPI
11. Rendering OpenAPI • Stoplight (paid service) • Swagger UI • Swagger Hub (paid service) • Swagger Viewer (Chrome extension)
16. Running mock server • Prism - OSS mock server for OpenAPI • Built by Stoplight • Returns response based on the OpenAPI schema • FE can use the mock server while BE is building the API • Docker image is available
17. Validate API response in feature tests • Make sure the actual response shape follows 
 the API contract • Spectator -> Didn’t work for me • Custom response assertion • league/openapi-psr7-validator • nyholm/psr7 • symfony/psr-http-message-bridge
18. Key take-aways • Design API contract before writing code • FE & BE develop the feature in parallel • OpenAPI is not just a documentation • Mock Server • Validate API Response in testing • Choose the right tool that works for you