API Design - Getting Started

Good API design isn't about following one right approach. It's about aligning on business goals first.

#1about 6 minutes

Defining the goals and purpose of API design

A good API design process starts by aligning on business goals, as disagreements often stem from mismatched objectives rather than technical choices.

#2about 5 minutes

Decoupling the client, API, and backend pillars

A solution's architecture should treat the client, API, and backend as independent pillars to avoid fragility and tight coupling during development.

#3about 4 minutes

Using JSON:API to focus on data, not format

The JSON:API specification provides a standard for structure, relationships, and operations, allowing developers to focus on business data instead of reinventing formats.

#4about 4 minutes

Use case: Designing a user registration flow

A multi-step registration process should be handled by the client, while the API provides distinct endpoints for validation and final resource creation.

#5about 6 minutes

Use case: Evolving a classifieds listing resource

An example of iteratively designing a listing resource by adding seller relationships and handling user-specific data requests through filtering.

#6about 4 minutes

Use case: Modeling conversations and messages

Designing a messaging system involves modeling conversations and messages while consolidating redundant resource types like 'seller' and 'buyer' into a single 'user' type.

#7about 2 minutes

Use case: Designing a unified search endpoint

A single search endpoint can return different resource types by using a generic 'search_result' resource with polymorphic relationships.

#8about 2 minutes

Key takeaways and further API design topics

A summary of core principles like focusing on content and naming, plus a look at other critical topics like documentation, security, and versioning.

#9about 12 minutes

Audience Q&A on tools, errors, and GraphQL

The speaker answers audience questions on topics including documentation tools like Postman, error handling strategies, and comparing JSON:API with GraphQL.