What is an API
API design is a core skill for backend engineers and a key topic in system design interviews.
Quick answer: What is an API
What is an API is covered here as a practical system design concept. API design is a core skill for backend engineers and a key topic in system design interviews. Use it to understand the APIs idea, where it appears in production systems, and how to discuss it clearly in interviews.
Focus on the problem being solved, the main design choice, the failure mode, and the tradeoff you would defend in front of a senior engineer. This page is part of the DosiBridge system design knowledge graph, so it links related concepts, interview problems, tradeoffs, and references instead of leaving the topic isolated.
What What is an API Actually Means
An API (Application Programming Interface) is a contract that defines how two software systems communicate. It specifies the requests a client can make, the format of those requests, and the expected responses. APIs are the building blocks of modern software architecture — every microservice, third-party integration, and frontend-backend interaction uses APIs.
When to Use It (and When Not To)
API design is a core skill for backend engineers and a key topic in system design interviews. A well-designed API is intuitive, consistent, versioned, and backward-compatible. A poorly designed API creates technical debt that is hard to fix once clients depend on it.
The Architecture
A client sends an HTTP request to an API endpoint (e.g., GET /api/users/123). The server processes the request — authenticates the caller, validates the input, queries the database, transforms the data — and returns an HTTP response with a status code (200 OK) and body (JSON data).
API design involves choosing resources, defining endpoints, selecting HTTP methods, designing request/response schemas, handling errors consistently, and documenting everything.
Key Principles
- REST: The most common API style. Uses HTTP methods (GET, POST, PUT, DELETE) on resources identified by URLs. Stateless, cacheable, standardized.
- GraphQL: Query language that lets clients request exactly the data they need. Reduces over-fetching and under-fetching. Used by Facebook, GitHub, Shopify.
- gRPC: Binary protocol using Protocol Buffers. High-performance, strongly typed, supports streaming. Used for internal microservice communication.
- Versioning: APIs evolve. Use URL versioning (/api/v1/) or header versioning to avoid breaking existing clients.
- Authentication: APIs use tokens (JWT, OAuth2) or API keys to authenticate and authorize requests.
Who Does This Well
Stripe API is considered the gold standard of API design — RESTful, consistent, well-documented, with idempotency support and versioning.
GitHub API offers both REST and GraphQL endpoints, letting clients choose the best fit.
Twilio API demonstrates excellent error handling — every error includes a human-readable message, error code, and link to documentation.
The Hard Parts Nobody Talks About
- Inconsistent naming conventions across endpoints
- Not handling errors with proper HTTP status codes
- Breaking backward compatibility without versioning
- Over-engineering the API for rare use cases
The Tradeoffs
- REST vs GraphQL: REST is simpler and more cacheable; GraphQL is more flexible and reduces round trips.
- REST vs gRPC: REST is human-readable and browser-friendly; gRPC is faster and type-safe.
- Public vs Internal APIs: Public APIs need versioning and backward compatibility; internal APIs can evolve faster.
Interview Angles
- What makes a good API?
- How do you version an API?
- What is the difference between REST, GraphQL, and gRPC?
- How do you handle backward compatibility?
Keep Learning
Production angle: an API is a product boundary
An API is not just a function exposed over HTTP. It is a promise that one team, service, mobile app, partner, or customer can depend on. Good APIs hide internal implementation details while making business capabilities predictable: create an order, search a catalog, start a ride, upload a file, or join a meeting.
API boundaries that matter
- Public API: external developers or customers use it; stability, documentation, auth, rate limits, and versioning are critical.
- Internal service API: other services use it; ownership, schema evolution, and observability matter most.
- Backend-for-frontend API: optimized for a specific web or mobile experience.
- Event API: asynchronous contract where services communicate through facts instead of direct calls.
This distinction makes the page different from a generic API design article. The important question is not "REST or GraphQL?" first. The first question is who depends on this boundary and what change would break them?
Example: order API
A simple 'POST /orders' endpoint may look straightforward, but the API contract includes authentication, idempotency key behavior, validation errors, payment state, response shape, retry safety, and webhook/event behavior after creation. If the client times out after sending the request, can it safely retry? If inventory is pending, does the API return '202 Accepted' or create an order in a pending state? These decisions define the user experience.
What makes an API high quality
- Clear nouns and actions that map to business concepts.
- Explicit authentication and authorization rules.
- Stable response schemas with backward-compatible changes.
- Consistent error format with machine-readable codes.
- Pagination, filtering, and sorting for collections.
- Idempotency for dangerous retries.
- Rate limits and quotas documented up front.
- Observability: request IDs, latency metrics, and error classes.
Interview-ready answer
When asked "what is an API," answer as a systems designer: an API is a stable interface for a capability. It separates consumers from implementation, lets teams evolve independently, and creates a contract around data, behavior, errors, security, performance, and versioning.
Original DosiBridge notes for What is an API
This section is written specifically for this page, not copied from a general system-design checklist. The useful way to study What is an API is to connect the concept to an integration boundary where bad contracts become customer-facing outages. That framing changes the design discussion from definitions to operating choices.
What makes this topic distinct
- Contract Evolution: For What is an API, decide the contract evolution before choosing tools; otherwise the design looks clean but fails when what changes.
- Idempotency: For What is an API, decide the idempotency before choosing tools; otherwise the design looks clean but fails when is changes.
- Pagination: For What is an API, decide the pagination before choosing tools; otherwise the design looks clean but fails when an changes.
- Error Shape: For What is an API, decide the error shape before choosing tools; otherwise the design looks clean but fails when api changes.
- Consumer Compatibility: For What is an API, decide the consumer compatibility before choosing tools; otherwise the design looks clean but fails when what changes.
Production review question
If a team adopts What is an API, what observable signal proves it helped instead of only making the architecture diagram more fashionable?
Practical metric to track
Track what-api health as a named dashboard or review item: combine one user-facing metric, one saturation metric, and one correctness metric. For What is an API, this keeps the discussion grounded in behavior that can be measured after deployment instead of generic advice that sounds good in an interview but never gets verified.