API Design & REST/GraphQL
RESTful APIs, GraphQL, API security, versioning strategies
What is a REST API and what are its core constraints?
REST (Representational State Transfer) is an architectural style for distributed hypermedia systems defined by six constraints: client-server separation, statelessness, cacheability, uniform interface, layered system, and optional code-on-demand. Resources are identified by URIs and manipulated through standard HTTP methods. [Source: Roy Fielding's Doctoral Dissertation, UC Irvine]
What is the difference between REST and GraphQL?
REST uses multiple fixed endpoints returning server-defined data structures, while GraphQL exposes a single endpoint where clients specify exactly the data fields they need. GraphQL eliminates over-fetching and under-fetching but adds query complexity; REST benefits from simpler HTTP caching and broader tooling support. [Source: GraphQL Foundation / graphql.org]
Which HTTP methods are used in RESTful APIs and what do they mean?
RESTful APIs use GET (retrieve), POST (create), PUT (replace), PATCH (partial update), and DELETE (remove) as the primary HTTP methods. GET and HEAD must be safe and idempotent; PUT and DELETE must be idempotent. These semantics are formally specified in RFC 9110 by the IETF. [Source: IETF RFC 9110]
What are the main strategies for versioning a REST API?
The four primary REST API versioning strategies are URI path versioning (/v1/resource), query parameter versioning (?version=1), custom request header versioning, and Accept header (content negotiation) versioning. URI path versioning is most widely adopted for its explicitness, though header-based versioning better preserves URI semantics per REST principles. [Source: IETF RFC 9110]
What is a GraphQL schema and why is it important?
A GraphQL schema is the strongly-typed contract between client and server, defining all available types, queries, mutations, and subscriptions using the GraphQL Schema Definition Language (SDL). It serves as the single source of truth for API capabilities, enables automatic validation, and powers introspection—allowing clients to discover the API at runtime. [Source: GraphQL Specification, GraphQL Foundation]
What are the most important security best practices for REST APIs?
OWASP's API Security Top 10 identifies broken object-level authorization, broken authentication, and excessive data exposure as leading risks. Best practices include using OAuth 2.0 with PKCE for authorization, enforcing HTTPS/TLS, validating all inputs, implementing rate limiting, and avoiding sensitive data in URIs. [Source: OWASP API Security Project]
What is OAuth 2.0 and how does it protect APIs?
OAuth 2.0 is an authorization framework defined in IETF RFC 6749 that enables third-party applications to obtain limited access to an HTTP service without exposing user credentials. It uses access tokens issued by an authorization server, supporting grant types including authorization code, client credentials, and device authorization flow. [Source: IETF RFC 6749]
When should you use OAuth 2.0 versus API keys for API authentication?
API keys are simple static tokens best suited for server-to-server communication where the client is trusted and user-context is unnecessary. OAuth 2.0 is required when delegating access on behalf of a user, supporting scoped permissions, or enabling third-party integrations—it provides token expiry, revocation, and fine-grained authorization that static API keys cannot. [Source: IETF RFC 6749 / OWASP API Security]
What is a JWT and how is it used in API authentication?
A JSON Web Token (JWT), defined in IETF RFC 7519, is a compact, URL-safe means of representing claims between two parties using a digitally signed JSON payload. In APIs, JWTs serve as bearer tokens carrying identity and authorization claims, allowing stateless verification without a database lookup on every request. [Source: IETF RFC 7519]
What does statelessness mean in REST APIs and why does it matter?
REST statelessness requires that each client request contain all information necessary for the server to process it—no session state is stored server-side between requests. This constraint improves scalability and reliability because any server instance can handle any request, enabling horizontal scaling and simplifying fault tolerance in distributed systems. [Source: Roy Fielding's Doctoral Dissertation, UC Irvine]
What HTTP status codes should REST APIs use and when?
RFC 9110 defines HTTP status codes for REST responses: 2xx for success (200 OK, 201 Created, 204 No Content), 3xx for redirection, 4xx for client errors (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests), and 5xx for server errors. Accurate status codes are essential for client error handling. [Source: IETF RFC 9110]
What is the N+1 problem in GraphQL and how is it solved?
The N+1 problem occurs when a GraphQL resolver fetches a parent list (1 query) then issues a separate database query per item (N queries), causing severe performance degradation. The standard solution is the DataLoader pattern—a batching and caching utility that consolidates N queries into a single batched request per request cycle. [Source: GraphQL Foundation Documentation]
How should REST APIs implement rate limiting?
Rate limiting restricts how many requests a client can make in a time window, protecting APIs from abuse and ensuring fair usage. Best practice per IETF RFC 6585 is to return HTTP 429 Too Many Requests with a Retry-After header. Common algorithms include token bucket, sliding window, and fixed window counters, implemented at the gateway or application layer. [Source: IETF RFC 6585]
What is the best format for REST API error responses?
IETF RFC 7807 (Problem Details for HTTP APIs) defines a standardized JSON error format with fields: type (URI), title, status, detail, and instance. Using this standard enables consistent, machine-readable error responses across services, improving API usability and client developer experience without requiring custom error schema documentation. [Source: IETF RFC 7807]
How does HTTP caching work in REST APIs?
REST APIs leverage HTTP caching through response headers defined in RFC 9111: Cache-Control directives (max-age, no-cache, private), ETag for conditional requests (304 Not Modified), and Last-Modified. Proper caching reduces server load and latency; REST's stateless, resource-oriented design makes it naturally compatible with standard HTTP cache infrastructure. [Source: IETF RFC 9111]
What is the OpenAPI Specification and why should API designers use it?
The OpenAPI Specification (OAS), formerly Swagger, is a language-agnostic standard maintained by the OpenAPI Initiative (Linux Foundation) for describing RESTful APIs in YAML or JSON. It defines endpoints, request/response schemas, authentication, and parameters, enabling automated documentation generation, client SDK generation, and contract-first API development workflows. [Source: OpenAPI Initiative / Linux Foundation]
How do you maintain backward compatibility when evolving an API?
Backward-compatible API changes include adding optional request parameters, adding new response fields, and adding new endpoints. Breaking changes—removing fields, changing data types, altering authentication—require a new API version. Microsoft's REST API Guidelines recommend maintaining at least one prior version and providing deprecation notices with sunset headers per RFC 8594. [Source: IETF RFC 8594 / Microsoft REST API Guidelines]
How should you deprecate an API endpoint or version?
IETF RFC 8594 defines the Sunset HTTP header to communicate the date after which a resource will be unavailable, enabling clients to plan migrations. Best practice combines the Sunset header with a Deprecation header (RFC draft), updated OpenAPI documentation, changelog notices, and a minimum 6–12 month deprecation window before removal. [Source: IETF RFC 8594]
What are the unique security risks of GraphQL APIs compared to REST?
GraphQL's flexible query model introduces risks absent in REST: introspection exposure (leaking schema to attackers), deeply nested query attacks causing denial of service, batching abuse amplifying request costs, and field-level authorization gaps. OWASP recommends disabling introspection in production, enforcing query depth/complexity limits, and implementing field-level authorization checks. [Source: OWASP API Security Project]
When should you choose GraphQL over REST for a new API?
GraphQL excels when clients have highly variable data requirements, when aggregating data from multiple sources, or when supporting multiple client types (mobile, web, IoT) with different bandwidth constraints. REST is preferable for simple CRUD services, file uploads, heavy HTTP caching needs, or teams without GraphQL expertise—the GraphQL Foundation's documentation details these tradeoffs explicitly. [Source: GraphQL Foundation / graphql.org]
What is an API gateway and what functions does it serve?
An API gateway is a server that acts as the single entry point for client requests, handling cross-cutting concerns including request routing, authentication and authorization, SSL termination, rate limiting, load balancing, request/response transformation, and observability. It decouples clients from backend service topology, enabling independent service evolution without breaking API contracts. [Source: NIST SP 800-204A]