apidays LIVE Australia - Building Business Ecosystems Contract-first API development with Spot Francois Wout, Developer Happiness Engineer at Airtasker

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

5. Typical
development process

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

16. Contract-first
development process

17. ��🏻♂Let's launch bookings on Web!
��🏼 💻Here is a draft API contract.
PM
…
��🏼 💻OK, I'll start designing an API to fetch bookings.

18. Draft API contract

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

23. OpenAPI
(Swagger)

24. OpenAPI
(Swagger)

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

28. Source:
openapi.tools

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
}

32. Introducing Spot
https://github.com/airtasker/spot

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

36. Developer experience

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