apidays LIVE Australia 2020 - Contract-first API development with Spot by Francois Wout
0 likes2,434 views
The document discusses contract-first API development and the introduction of Spot, a structured tool for building APIs in JSON. It highlights the challenges faced with unexpected API responses due to lack of documentation and collaboration, advocating for a more formalized API contract process. Spot allows for easier drafting, collaborative feedback, client code generation, and contract testing, while being compatible with existing workflows.
apidays LIVE Australia 2020 - Contract-first API development with Spot by Francois Wout
- 1. Contract-first API development The journey that led to Spot @fwouts
- 2. François Wouts Software EngineerSoftware EngineerDeveloper Happiness Engineer
- 3. Airtasker has three client apps
- 4. Cross-functional teams � �🏾 ��🏻 💻��🏼 💻��🏼 💻������🏼 UX PM
- 6. ��🏼 💻Done! The endpoint is /bookings. ��🏻♂Let's launch bookings on Web!PM … ��🏼 💻OK, I'll implement an API endpoint to fetch bookings.
- 7. ��🏼 💻Let me add this to the endpoint. � 👌 � �🏾 �� Where do I find the scheduled date? ��🏼 💻I've added `scheduled_date`. It's an int timestamp but it can be null too. …
- 8. 🚀
- 9. ✅
- 10. 1 month later
- 11. ��🏻♂Let's launch bookings on iOS! ��🏼 💻/bookings ��🏼 💻What's the endpoint called? ��🏼 💻👌 PM
- 12. 🚀💥
- 13. ��🏼 💻It's expected for cancelled bookings. ��🏼 💻Why would it return null? 📱💥 JSON deserialisation error Expected int, got null for property scheduled_date ��🏼 💻😰
- 14. What happened? 💥 iOS app crashed due to unexpected response payload 🚫 Web engineer blocked until API implemented 🚧 API had to be reworked
- 15. Why did this happen? ⚠ API was not explicitly documented ⚠ 💔 Client engineers were not consulted
- 17. ��🏻♂Let's launch bookings on Web! ��🏼 💻Here is a draft API contract. PM … ��🏼 💻OK, I'll start designing an API to fetch bookings.
- 19. � �🏾 �� How about adding scheduled_date too? ��🏼 💻👍 I added scheduled_date of type int or null. ��🏼 💻Done! Suggestion: scheduled_date of type string ��🏻 💻
- 20. � �🏾 ����🏻 💻✅ ✅ ✅ ��🏼 💻Thanks! I'll start implementing now. ��🏼 💻👍 I've added a pagination cursor. Will the endpoint be paginated? ��🏼 💻
- 21. REST API documentation formats
- 22. Sharing a doc Simple and helpful Very collaborative Leads to a better API - Details can be missed - Informal review process - Easily gets out of date
- 25. POST /users { "email": "f@zenc.io", "password": "hunter2" } Example: A simple API 201 Created { "user_id": "f123" }
- 26. OpenAPI (Swagger) definitions: CreateUserRequest: type: "object" properties: email: type: "string" password: type: "string" CreateUserResponse: type: "object" properties: user_id: type: "string" paths: /users: post: operationId: "createUser" parameters: - in: "body" name: "body" required: true schema: $ref: "#/definitions/CreateUserRequest" responses: "201": schema: $ref: "#/definitions/CreateUserResponse" definitions: CreateUserRequest: type: "object" properties: email: type: "string" password: type: "string" required: - "email" - "password" CreateUserResponse: type: "object" properties: user_id: type: "string" required: - "user_id"
- 27. OpenAPI (Swagger) Structured Official format Can describe most REST APIs (JSON or XML) - Fairly complex (spec = 56 pages long) - Difficult to write by hand - Difficult to review diffs
- 30. ● Designed for editing ● Still hard to review OpenAPI diffs GUI editors � �🏾 ��🏻 💻 �� ��🏼 💻 ��
- 31. Our REST API is JSON ● JSON = JavaScript Object Notation ● JavaScript types = TypeScript JSON TypeScript var payload = { "name": "Spot", "stars": 151 } type Payload = { name: string, stars: number }
- 33. POST /users { "email": "f@zenc.io", "password": "hunter2" } Example: A simple API 201 Created { "user_id": "f123" }
- 34. @endpoint({ method: "POST", path: "/users" }) class CreateUser { @request request(@body body: CreateUserRequest) {} @response({ status: 201 }) success(@body body: CreateUserResponse) {} } type CreateUserResponse = { user_id: string; } type CreateUserRequest = { email: string; password: string; } paths: /users: post: operationId: "createUser" parameters: - in: "body" name: "body" required: true schema: $ref: "#/definitions/CreateUserRequest" responses: "201": schema: $ref: "#/definitions/CreateUserResponse" definitions: CreateUserRequest: type: "object" properties: email: type: "string" password: type: "string" required: - "email" - "password" CreateUserResponse: type: "object" properties: user_id: type: "string" required: - "user_id" OpenAPI for comparisonSpot (TypeScript)
- 35. type CreateUserRequest = { email: string; password: string; location?: Location; } type Location = { suburb: string | null; country: Country; } type Country = 'AU' | 'UK' | 'FR'; TypeScript is (almost) intuitive omittable field required but nullable string enum components: schemas: Country: type: string enum: - AU - UK - FR CreateUserRequest: type: object properties: email: type: string password: type: string location: $ref: '#/components/schemas/Location' required: - email - password Location: type: object properties: suburb: type: string nullable: true country: $ref: '#/components/schemas/Country' required: - suburb - country
- 38. Spot Structured Easy to write Easy to review diffs Editor autocomplete - Limited to JSON
- 39. Spot Workflow 1. Draft API contract with Spot (e.g. in VS Code) 2. Send a PR to interested engineers to gather feedback 3. Merge the PR 4. Then in parallel: ○ API engineer implements the new API ○ Client engineers implement new features based on the API Upfront API design facilitates parallel development
- 40. What about OpenAPI? ✅ Spot generates OpenAPI!
- 41. Tooling ● Documentation ○ spot docs api.ts ● Client code generation ○ leveraging OpenAPI client generators (e.g. SwiftGen) ○ no more implementation mistakes! ● API contract testing ○ https://github.com/airtasker/spot/wiki/Contract-Testing ● Linting based on API guidelines ○ spot lint api.ts ● Mock API server ○ spot mock api.ts
- 42. Probably. ● No need to be familiar with TypeScript ○ quickly adopted at Airtasker by Ruby, Kotlin, Swift engineers ● Easy to integrate into your existing PR review process ● ⚠ Spot is only for JSON REST APIs ○ alternative to GraphQL, gRPC and Thrift ○ Spot is inspired by gRPC ● It's still early days (our docs need some ❤) Is Spot good for my team?
- 43. Want to learn more? Spot is open source! https://github.com/airtasker/spot
- 44. Thank you! @fwouts Come work with me at Airtasker! We're hiring: ● Senior Software Engineers ● VP of Engineering https://fwouts.com