> Markdown version of [/videos/33-api-design-getting-started?t=728](https://www.wearedevelopers.com/videos/33-api-design-getting-started?t=728). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

# API Design - Getting Started

Stop reinventing data conventions. Treat your API as a stateless enabler. Learn how standardized JSON frameworks build resilient, maintainable backend ecosystems.

- **Speakers:** Alen Pokos
- **Event:** WeAreDevelopers LIVE
- **Published:** August 28, 2020
- **Duration:** 44:15
- **URL:** https://www.wearedevelopers.com/videos/33-api-design-getting-started

## Summary

Effective API design serves as the critical functional bridge connecting diverse applications, aligning technical architecture directly with core business goals. A robust API functions by balancing three pillars—the client, the backend, and the API itself—while actively avoiding the common pitfall of tight coupling where endpoints merely mirror backend logic or dictate client UI states. Instead of constantly reinventing data conventions, teams can adopt rigorous standards like the JSON API specification. This architectural decision enables developers to shift their focus entirely onto what data or functionality is provided rather than debating how it should be structured or formatted. Practical API execution shines when treated as a stateless enabler rather than an omnipotent controller. For instance, multi-step user registrations should offload UI progression to the client while the API strictly handles data validation and persistence. As requirements organically evolve—like appending granular seller details to classified ads or managing complex participant redundancy in messaging features—developers can elegantly manage complexity through standardized resource relationships, native polymorphism, and sparse fieldsets. Ultimately, mitigating resource type bloat, leaning on semantic HTTP status codes, and completely isolating endpoint formatting from transient front-end redesigns yields a highly resilient, maintainable ecosystem.

**Keywords:** api design principles, json api specification, restful architecture patterns, backend decoupling, resource oriented interfaces, endpoint data modeling, semantic http status codes, api pagination strategies, relational data payloads, api error handling, graphql alternatives, client state management, stateless request model, sparse fieldsets

## Chapters

1. **Defining web APIs and their primary business purposes** (02:55) — Connecting separate application spaces by defining standardized web interfaces that achieve specific business objectives.
1. **Understanding the core concepts of API design** (04:49) — Navigating disagreements around application systems by defining specific business purposes, usability bounds, and technical constraints.
1. **Balancing the client, API, and backend pillars** (07:59) — Ensuring reliable system architecture by keeping the client, API, and backend functioning cohesively without tight technical coupling.
1. **Leveraging the JSON API standard for data structure** (12:08) — Resolving formatting indecisions by utilizing the JSON API standard to rapidly orient relationships and structure documents.
1. **Designing a user registration process with separate endpoints** (15:27) — Removing complex multi-step state tracking from the server by utilizing separate endpoints that shift validation responsibility to client applications.
1. **Evolving listing resource designs for classified platforms** (18:59) — Adapting to new data requirements by keeping items isolated and associating complex seller profiles through explicit resource relationships.
1. **Implementing user-specific filtering and contextual endpoints** (22:49) — Tackling personal data retrieval challenges by providing standard identifier filters and context-aware URL pathways.
1. **Modeling conversations and messages to reduce resource redundancy** (24:31) — Preventing endpoint overload by generalizing seller and buyer identities into reusable conversation participants and implicit resource bindings.
1. **Managing resource types to prevent API maintenance complexities** (28:04) — Avoiding maintenance nightmares caused by overly specific endpoint types by consolidating participants into a generic system entity.
1. **Designing polymorphic resource endpoints for search functionalities** (28:53) — Returning diverse search matches efficiently by leveraging relationship wrappers that identify unique document varieties in a shared endpoint payload.
1. **Establishing core principles for data focus and naming** (30:38) — Escaping theoretical gridlock by standardizing naming layouts and prioritizing clear data provision over flawless architectural designs.
1. **Clarifying the boundary between requirements and API design** (32:42) — Maintaining scope by viewing API engineering as a direct tool to solve core product requirements instead of inventing new expectations.
1. **Tools for API documentation and relationship visualization** (33:39) — Improving system comprehensibility by employing external tools to test requests and map out complete resource relationship diagrams.
1. **Adopting standard error handling and endpoint testing practices** (35:39) — Guaranteeing reliable client responses by integrating standardized semantic status codes and automated postman testing procedures.
1. **Comparing GraphQL capabilities against the JSON API standard** (37:01) — Evaluating technology trade-offs by choosing between the unconstrained flexibility of GraphQL and the rapid delivery of standardized JSON structures.
1. **Choosing readable enum values over numeric backend identifiers** (37:57) — Preventing system confusion by substituting internal database numeric integers with human-readable string values for public usage.
1. **Optimizing performance across JSON methodologies and backend stacks** (39:15) — Overcoming endpoint slowness by recognizing that performance ultimately relies on targeted caching and specialized backend stack optimizations.
1. **Handling data pagination and endpoint versioning strategies** (40:43) — Structuring large datasets for rapid iteration by implementing systematic document pagination and transparent routing patterns.
1. **Applying business rules and permissions within API standards** (42:41) — Imposing correct boundaries by translating standard business terminology into universally recognized HTTP rules and permission constraints.

## Related Moments

- [Summarizing key engineering lessons for platform API development](https://www.wearedevelopers.com/videos/942-insights-from-building-the-canva-developers-platform-to-empower-185-million-designers) (from "Insights from building the Canva Developers Platform to empower 185 million designers")
- [Designing outstanding APIs with simplicity, safety, and evolvability](https://www.wearedevelopers.com/videos/942-insights-from-building-the-canva-developers-platform-to-empower-185-million-designers) (from "Insights from building the Canva Developers Platform to empower 185 million designers")
- [Designing use-case driven APIs and consolidating broad endpoints](https://www.wearedevelopers.com/videos/1574-lessons-learned-from-observing-a-billion-api-requests) (from "Lessons learned from observing a billion API requests")
- [Evaluating benefits and drawbacks of common API formats](https://www.wearedevelopers.com/videos/1195-the-great-api-debate-rest-graphql-or-grpc) (from "The Great API Debate: REST, GraphQL, or gRPC?")
- [Establishing a concrete vision for REST API development](https://www.wearedevelopers.com/videos/100208-rest-api-antipatterns) (from "Rest API Antipatterns")
- [Standardizing design rules using the API Stylebook](https://www.wearedevelopers.com/videos/1932-for-the-rest-of-us-api-first-and-conway-s-law) (from "For the REST of us: API First and Conway’s Law")

## Related Articles

- [Douglas Crockford - JSON and Beyond](https://www.wearedevelopers.com/magazine/481-douglas-crockford-json-and-beyond)
- [How to Avoid Over-Engineering](https://www.wearedevelopers.com/magazine/546-how-to-avoid-over-engineering)
- [Dev Digest 139 - Soft and hard queries](https://www.wearedevelopers.com/magazine/487-dev-digest-139-soft-and-hard-queries)
- [Navigating the AI Shift](https://www.wearedevelopers.com/magazine/629-navigating-the-ai-shift)

## Related Jobs

- [AI Full Stack Engineer](https://www.wearedevelopers.com/jobs/ext/1354435-ai-full-stack-engineer) at **Almedia**
- [Principal Software Engineer](https://www.wearedevelopers.com/jobs/ext/267591-principal-software-engineer) at **Twilio**
- [Staff Software Engineer](https://www.wearedevelopers.com/jobs/ext/1425755-staff-software-engineer) at **GitHub**
- [Principal Software Engineer](https://www.wearedevelopers.com/jobs/ext/146806-principal-software-engineer) at **Twilio**
- [Senior Software Engineer, Client Apps Platform](https://www.wearedevelopers.com/jobs/ext/1773893-senior-software-engineer-client-apps-platform) at **GitHub**
- [Principal Software Engineer](https://www.wearedevelopers.com/jobs/ext/115163-principal-software-engineer) at **Twilio**