REST API Interview Questions

Statelessness means each request from a client to the server must contain all the information needed to process it, and the server doesn't store any client session state between requests. Each request is handled independently, which makes REST APIs easier to scale since any server instance can handle any request.

GET retrieves a resource without changing it. POST creates a new resource. PUT updates an existing resource, typically replacing it entirely. PATCH applies a partial update to a resource. DELETE removes a resource.

A resource is any piece of data or object the API exposes, like a user, an order, or a product, typically identified by a unique URL. REST is built around manipulating these resources through standard HTTP methods rather than exposing custom actions or verbs in the URL itself.

PUT typically replaces an entire resource with the data provided in the request, meaning any field not included is often reset or removed. PATCH applies a partial update, changing only the specific fields included in the request while leaving the rest of the resource unchanged.

A status code is a three-digit number returned with every HTTP response, indicating whether the request succeeded, failed, or needs further action. It matters because a client can programmatically check the status code to determine how to handle the response, without needing to parse the response body just to know if something went wrong.

2xx codes indicate success, like 200 OK or 201 Created. 3xx codes indicate redirection. 4xx codes indicate a client error, like 404 Not Found or 400 Bad Request. 5xx codes indicate a server error, like 500 Internal Server Error, meaning something went wrong on the server's side rather than the client's.

401 Unauthorized means the request lacks valid authentication credentials, so the server doesn't know who's making the request. 403 Forbidden means the server does know who's making the request, but that identity doesn't have permission to access the requested resource.

JSON, JavaScript Object Notation, is a lightweight, text-based data format representing structured data as key-value pairs and arrays. It's commonly used in REST APIs because it's easy for both humans to read and machines to parse, and nearly every programming language has good support for working with it.

A path parameter is embedded directly in the URL's path, like /users/42, typically identifying a specific resource. A query parameter is appended after a question mark, like /users?role=admin, typically used for filtering, sorting, or optional options rather than identifying a specific resource.

An endpoint is a specific URL that a client sends a request to, representing a particular resource or collection of resources, like /api/users or /api/orders/17. Combined with an HTTP method, an endpoint defines a specific operation the API supports.

Headers carry metadata about the request that isn't part of the actual data being sent, like the content type of the body, an authentication token, or what response format the client accepts. They let the client and server communicate important context alongside the actual request data.

Content-Type tells the receiving side what format the data in the request or response body is in, like application/json for JSON data. Without it, the server or client wouldn't reliably know how to correctly parse the body's contents.

An idempotent operation produces the same result no matter how many times it's repeated with the same input. GET, PUT, and DELETE are generally idempotent, since making the same request multiple times has the same effect as making it once, while POST is typically not, since repeating it usually creates multiple new resources.

API versioning lets an API evolve over time, introducing breaking changes, without disrupting clients still relying on an older version's behavior. Common approaches include putting the version in the URL, like /v1/users, or in a request header.

A synchronous call blocks the client, waiting for the server's response before continuing execution. An asynchronous call lets the client continue doing other work while waiting for the response, typically handling the result through a callback, promise, or similar mechanism once it eventually arrives.

CRUD stands for Create, Read, Update, and Delete, the four basic operations performed on data. REST APIs commonly map these directly to HTTP methods: POST for create, GET for read, PUT or PATCH for update, and DELETE for delete.

An API key is a unique identifier passed with a request, typically used to authenticate the calling application and track its usage. It's a simpler form of authentication than something like OAuth, commonly used for public APIs where identifying the calling application matters more than identifying an individual user.

REST stands for Representational State Transfer. It was introduced by Roy Fielding in his 2000 doctoral dissertation, describing REST as an architectural style rather than a strict protocol or standard, which is why REST APIs can vary somewhat in how strictly they follow every original constraint.

A web service is a broader term for any service that communicates over a network, which can use various protocols like SOAP or REST. REST API specifically refers to a web service built following REST's architectural principles, using standard HTTP methods and typically exchanging JSON.

The Accept header tells the server what response format the client can handle, like application/json, letting the server return data in a format the client actually understands. If a server supports multiple response formats, this header helps it choose the right one for that particular client.

A collection represents a set of resources, like /users representing all users, typically accessed with GET to list them or POST to add a new one. A single resource, like /users/42, represents one specific item within that collection, typically accessed with GET, PUT, PATCH, or DELETE.

GET typically sends data through the URL itself, as query parameters, and shouldn't be used to send sensitive data since URLs can be logged or cached. POST sends data in the request body, which is more suitable for larger amounts of data or sensitive information, though it still isn't inherently secure without additional measures like HTTPS.

404 Not Found is returned when the requested resource doesn't exist at the given URL. It's one of the most common status codes clients encounter, whether because a resource was deleted, never existed, or the client made a typo in the URL.

A public API is exposed for external developers or partners to use, often requiring registration and an API key, and typically documented for outside consumption. A private API is used only internally within an organization, often between an organization's own services, without needing the same level of external documentation or access control.

REST is an architectural style using standard HTTP methods and typically exchanging lightweight JSON, while SOAP is a strict protocol using XML messages with a rigid, formally defined structure. REST is generally simpler and more widely used for modern web APIs, while SOAP is still used in some enterprise contexts that need its stricter contracts and built-in features like formal security standards.

A URI, Uniform Resource Identifier, is a general term for a string that identifies a resource. A URL, Uniform Resource Locator, is a specific type of URI that also tells you how to locate that resource, like specifying the protocol and address, which is what's typically used to actually access a REST API's resources.

The Location header is commonly returned with a 201 Created response, telling the client the URL of the newly created resource. This lets the client immediately know where to find or further interact with the resource it just created, without needing to guess or construct the URL itself.

Pagination breaks a large collection of results into smaller chunks, or pages, returned across multiple requests rather than all at once. It's used because returning an entire large dataset in a single response would be slow and consume excessive memory and bandwidth on both the client and server.

400 Bad Request generally means the request itself is malformed or invalid, like broken JSON syntax the server can't even parse. 422 Unprocessable Entity means the request is syntactically valid and understood, but the actual data fails a validation rule, like a required field being missing or a value being out of an acceptable range.

HATEOAS, Hypermedia as the Engine of Application State, is a REST constraint where a response includes links to related actions or resources, letting a client navigate the API dynamically rather than needing to hardcode every URL it might need. In practice, many REST APIs skip full HATEOAS implementation since it adds complexity many use cases don't genuinely need.

OPTIONS asks the server what HTTP methods and other options are available for a specific resource, without actually performing an operation on it. It's commonly used automatically by browsers as a preflight request before certain cross-origin requests, checking what's allowed before the real request is sent.

A request body carries the actual data being sent to the server, separate from the URL and headers. POST, PUT, and PATCH typically include a request body carrying the data to create or update, while GET requests typically don't include a body, relying instead on the URL and query parameters.

REST design is organized around resources and standard HTTP methods acting on them, like GET /users/42. RPC, Remote Procedure Call, style design is organized around actions or functions being called directly, like /getUser or /createOrder, which can feel more natural for certain operations but doesn't follow REST's resource-oriented conventions.

HTTPS encrypts data in transit between the client and server, protecting sensitive information like authentication tokens or personal data from being intercepted. Even a simple API benefits from HTTPS, since any data sent over plain HTTP can be read or tampered with by anyone able to observe the network traffic.

Synchronous request-response requires the client to actively make a request and wait for a response. A webhook flips that around, where the server calls a URL the client registered in advance whenever a relevant event happens, letting the client be notified without needing to repeatedly poll the server for updates.

For authentication, I'd typically use token-based approaches like JWT or OAuth 2.0 rather than sending credentials with every request, letting a client obtain a token once and include it in subsequent requests. For authorization, I'd check the authenticated identity's permissions against the specific resource and action being requested, keeping that logic centralized rather than duplicated across endpoints.

API key authentication identifies the calling application with a static key, which is simple but offers limited granularity and is harder to revoke selectively. OAuth 2.0 supports delegated authorization, letting a user grant a third-party application limited access to their data without sharing their actual credentials, and it's the better choice when an API needs to support that kind of user-level, scoped access.

I'd track request counts per client, typically identified by API key or authenticated user, over a defined time window, rejecting requests that exceed the limit with a 429 Too Many Requests status code. Including headers indicating the current rate limit status and when it resets helps well-behaved clients adjust their request pace proactively rather than just hitting the limit repeatedly.

I'd return a consistent error structure across the entire API, including a clear, human-readable message, an application-specific error code beyond just the HTTP status, and ideally which specific field or condition caused the problem for validation errors. Consistency matters more than any single field's exact format, since it lets client code handle errors predictably across every endpoint.

Offset-based pagination uses a page number or a fixed offset and limit, which is simple to implement but can produce inconsistent results if records are added or removed between requests. Cursor-based pagination uses a pointer to a specific record as the starting point for the next page, which handles a changing dataset more reliably and performs better on very large datasets, at the cost of being somewhat less intuitive to implement and use.

I'd favor additive, backward-compatible changes whenever possible, adding new optional fields rather than changing or removing existing ones, so most changes don't require a new version at all. When a genuinely breaking change is unavoidable, I'd introduce a new version, commonly through the URL path, and maintain the previous version for a defined deprecation period so existing clients have time to migrate.

I'd generally expose the most commonly accessed nested relationship through a nested URL, like /orders/17/items, while also considering whether a flatter, separately queryable endpoint makes more sense for cases where clients need to search or filter across that nested data more flexibly. Over-nesting URLs too many levels deep tends to make an API harder to use, so I'd balance clarity against practical usability.

I'd use PATCH with a request body containing only the fields that actually need to change, leaving every other field on the resource untouched. This avoids the client needing to fetch the entire resource first just to resend unchanged fields along with the update, which PUT would typically require if used for the same purpose.

I'd use query parameters for these, like /products?category=electronics&sort=price&order=asc, keeping the parameter names clear and consistent across the API. For more complex filtering needs, I'd consider whether a dedicated search endpoint accepting a more structured query in the request body makes more sense than trying to cram complex logic into query parameters.

The N+1 problem happens when fetching a list of items requires one query to get the list, then a separate query for each item's related data, resulting in many more database queries than necessary. In REST API design, this often shows up when a client has to make one request to list resources, then a separate request per item to get related details, which a well-designed endpoint can often avoid by including that related data upfront.

I'd design a dedicated endpoint accepting an array of items in the request body, processing them together and returning a response indicating the outcome for each individual item, since a bulk operation partially succeeding and partially failing is common and needs to be communicated clearly. I'd avoid overloading the standard single-resource endpoint to handle both single and bulk cases, since that tends to make the API's behavior less predictable.

I'd use HTTP caching headers like Cache-Control and ETag, letting clients and intermediate proxies cache responses for data that doesn't change frequently, and validate whether cached data is still fresh without needing to re-fetch the entire response. For data that changes more often, a shorter cache duration or no caching at all keeps clients from acting on stale information.

An ETag is a unique identifier for a specific version of a resource, returned in a response header. A client can send that ETag back in a conditional request, letting the server quickly check whether the resource has changed since the client last fetched it, and return a lightweight 304 Not Modified response instead of resending the full resource if it hasn't.

I'd generally keep the API resource-oriented and consistent rather than building separate endpoints for each client, using optional query parameters to let a client request only the fields it actually needs, sometimes called a sparse fieldset. If the two clients' needs diverge significantly, a backend-for-frontend pattern, with a thin, client-specific layer sitting in front of the shared core API, is a reasonable alternative to duplicating the whole API.

I'd deprecate the field first, keeping it in the response but documenting that it will be removed, ideally paired with a warning header or documentation notice, giving existing clients time to stop relying on it. Only after a clear deprecation period, and ideally confirming through usage monitoring that clients have actually migrated, would I remove the field entirely, usually as part of a new API version.

CORS, Cross-Origin Resource Sharing, is a browser security mechanism that restricts web pages from making requests to a different domain than the one that served the page, unless the server explicitly allows it through specific response headers. It matters for a REST API because a frontend hosted on a different domain than the API needs the API to send the correct CORS headers, or the browser will block those requests entirely.

I'd wrap the actual data in a consistent envelope structure, with a data field holding the actual resources and a separate meta or pagination field holding information like total count, current page, and links to adjacent pages. Keeping this structure consistent across every collection endpoint makes client-side code that handles pagination reusable across the entire API.

I'd write automated tests covering each endpoint's expected behavior, both for successful requests and for expected error conditions like invalid input or missing authentication, ideally running these automatically as part of a CI pipeline. Contract testing, verifying the API's actual behavior matches its documented specification, adds another layer of confidence, especially for APIs consumed by many different client teams.

I'd use a standard specification format like OpenAPI, which lets documentation be generated consistently and even used to auto-generate client code or interactive documentation. Beyond just listing endpoints and parameters, including concrete request and response examples for both success and common error cases genuinely speeds up another developer's integration.

POST is typically used when the server assigns the resource's identifier, like generating a new auto-incrementing ID upon creation. PUT is typically used when the client already knows and specifies the resource's identifier upfront, like creating or replacing a specific resource at a known URL, since PUT is idempotent and expects a full resource representation at a known location.

I'd support an explicit query parameter, like ?expand=author,comments, letting a client request that related resources be embedded directly in the response when it genuinely needs them. Keeping this opt-in rather than always including every related resource avoids bloating the default response for clients that don't need that extra data.

I'd document a clear style guide covering things like pluralization, casing, and how nested resources are represented, and enforce it through code review and, where practical, automated linting against the API specification. Consistency matters most at the seams between endpoints a client actually uses together, so I'd prioritize catching drift there over chasing perfect uniformity everywhere at once.

I'd base that on genuine, observed access patterns rather than guessing, including commonly needed fields directly and moving rarely needed, expensive-to-compute, or large data behind a separate endpoint or an explicit expansion parameter. Over-including data every response tends to slow down the common case, while under-including it creates the N+1 request problem for the client.

I'd implement timeouts and circuit breakers around calls to downstream dependencies, failing fast with a clear 503 Service Unavailable response rather than letting requests hang indefinitely and cascade failure through the whole system. For non-critical dependencies, degrading gracefully, returning a partial response with cached or default data, is often better than failing the entire request outright.

An API gateway centralizes cross-cutting concerns, authentication, rate limiting, request logging, and routing, so individual backend services don't each need to reimplement them. I'd design it to route requests to the appropriate backend service based on the URL path, while keeping the gateway itself relatively thin, avoiding embedding business logic there that belongs in the actual services.

I'd favor additive changes, new optional fields, wherever possible, and use API versioning specifically for genuinely breaking changes rather than every minor adjustment. Monitoring which API version and which specific fields clients are actually using helps make an informed decision about when it's safe to actually remove a deprecated field or version, rather than guessing.

I'd have the client generate and send a unique idempotency key with the request, which the server stores alongside the result of processing that request. If the same idempotency key arrives again, the server returns the previously stored result rather than processing the operation a second time, which protects against duplicate processing from network retries or client-side errors.

I'd track request latency, error rates, and throughput per endpoint, with alerting tuned to that specific endpoint's normal baseline rather than a generic threshold across the whole API. Distributed tracing, following a single request across multiple internal services, becomes essential once an API's implementation spans more than one backend service.

I'd generally keep them as genuinely separate APIs with different rate limits, authentication requirements, and versioning cadences, rather than trying to serve both needs from a single unified API. Sharing the underlying business logic and data layer between them, while keeping the actual API surface and its operational characteristics distinct, avoids either use case compromising the other's needs.

I'd look at concrete signals, like clients needing to make many chained requests to assemble the data they actually need, evidence of significant over-fetching or under-fetching of data, or consistent client-side workarounds that suggest the API's shape doesn't match how it's actually being used. Those patterns often point toward a specific, targetable design improvement rather than requiring a wholesale rebuild.

I'd keep the external REST API contract stable throughout the migration, using an API gateway or facade layer to route requests to whichever backend, monolith or new microservice, currently owns that piece of functionality. This decouples the internal migration from what API consumers actually see, letting the migration happen incrementally without requiring every client to change at the same time.

I'd validate and sanitize all input server-side regardless of any client-side validation, since client-side checks can always be bypassed, and apply rate limiting to protect against abuse and brute-force attempts. Keeping dependencies patched, using HTTPS everywhere, and following the principle of least privilege for what data any given endpoint actually exposes rounds out a reasonably solid baseline beyond just the authentication layer.

I'd have the initial request kick off the operation and immediately return a 202 Accepted response along with a URL the client can poll to check the operation's status, rather than holding the connection open until the operation finishes. For clients that need more immediate notification, pairing this with a webhook callback once the operation completes avoids the client needing to poll repeatedly.

I'd define the API contract formally upfront, using a specification like OpenAPI, and treat changes to that published contract as requiring genuine review and communication, similar to how a team would treat a change to a shared library's public interface. Automated contract testing, verifying the actual implementation matches the published specification, catches drift before it becomes a production problem for teams depending on that contract.

I'd establish shared conventions for the things that genuinely affect consumers across teams, authentication patterns, error response structure, versioning approach, pagination style, while giving teams flexibility in their specific resource modeling for their own domain. Over-standardizing every small design decision tends to slow teams down without meaningfully improving the API ecosystem's overall usability.

I'd document the growing duplicated effort across teams, each reimplementing authentication, rate limiting, and logging slightly differently, along with the operational risk and inconsistency that creates. Framing the investment around developer time saved and consistency gained across the whole API surface, beyond just infrastructure cost, makes the case land with leadership focused on business outcomes.

I'd have an actual developer, ideally someone who wasn't involved in designing it, try to build something real against the API and pay close attention to where they get confused or need to guess. A technically correct API that requires extensive documentation or tribal knowledge to use correctly often has a design problem, beyond just being merely explainable through good docs.

I'd ground the disagreement in concrete evidence, the actual usage patterns and pain points from all affected teams, rather than treating it as a single team's preference versus another's. If a genuine tradeoff exists with no clean win-win, I'd make a call based on which consumers the API is actually meant to serve first, and be transparent with all affected teams about that reasoning.

I'd have them spend real time using APIs built by other teams, including ones with reputations for being awkward to integrate with, to build direct intuition for what makes an API genuinely pleasant versus merely functional to use. Having them own the full lifecycle of an API, including fielding real integration questions from other teams, builds that product-thinking faster than reviewing design documents alone.

I'd look at trend lines, whether integration friction and support questions about existing APIs are increasing over time, and whether new APIs are still following established conventions or drifting further from them as more teams build independently. Debt that's stable and well-documented is very different from debt that's actively compounding and actually blocking new integration work.

I'd weigh the genuine, ongoing demand for broader external access against the real cost of building and maintaining a full public API, documentation, versioning discipline, dedicated support, that a one-off integration wouldn't require. A single partner's specific need is often better served by a narrower, purpose-built integration, while genuine broad external demand justifies the investment in a proper public API.

I'd anchor that direction in where the business itself is heading, anticipated growth in external partnerships or platform ambitions, rather than adopting every new API design trend as it emerges. Building in periodic checkpoints to reassess as actual needs become clearer keeps the direction grounded in real requirements instead of speculation made too far in advance.

I'd weigh the actual volume and growth trajectory of external API consumers against the upfront cost of building genuine self-service infrastructure, documentation, sandbox environments, automated key provisioning. A small, stable number of partners is often served fine by manual processes, while a growing or strategically important partner ecosystem usually justifies the self-service investment.

I'd translate the technical tradeoffs into terms stakeholders actually care about, partner and customer impact, migration timeline, and the longer-term benefit to what the API can support going forward, rather than walking through the technical mechanics themselves. Being honest about the real short-term disruption a breaking change causes existing integrations, beyond just its eventual payoff, builds more durable trust than an overly optimistic pitch.

I'd track adoption and integration health signals, how many teams or partners are actually building on a given API, how often they run into friction serious enough to need direct support, and whether usage is growing or stagnating over time. Purely technical health metrics can look fine even while an API is quietly failing to serve its actual purpose of enabling other teams to build on it effectively.

I'd invest in documenting the API's actual current behavior honestly, including its inconsistencies, before attempting any significant cleanup, since undocumented inconsistent behavior fails in surprising ways when touched carelessly by consumers who assumed consistency. I'd push for incremental, backward-compatible improvement over time, with clear deprecation paths for the worst inconsistencies, rather than a risky, disruptive full redesign.

I'd calibrate the level of design rigor to how widely and how long the specific API is expected to be consumed, applying more care to foundational, broadly shared APIs and being more pragmatic about narrow, short-lived integrations. Treating every API with the same level of ceremony either slows down low-stakes work unnecessarily or, worse, under-invests in something that genuinely needed more care given how widely it would end up being depended on.

I'd periodically revisit whether REST remains the right fit for the organization's dominant integration needs, and whether newer needs, like real-time streaming data or more complex querying, are being forced awkwardly into REST patterns when a different approach, like GraphQL or event-driven APIs, would genuinely serve them better. A mature API strategy uses the right approach for each genuine need rather than defaulting to REST everywhere out of institutional habit.

I focus on getting them comfortable making the business case for platform investments in terms leadership actually cares about, and having them own relationships with API-consuming teams across the organization rather than only being consulted reactively when something breaks. Pairing them on organization-wide initiatives where they have to negotiate priorities and tradeoffs across many teams builds the influence that deep technical skill alone doesn't teach.

I'd make the actual cost of not investing concrete and specific, integration friction slowing down partner and internal team velocity, inconsistent API quality creating support burden, rather than arguing for the investment in the abstract. Even when the final prioritization decision goes against my recommendation, making sure it's an informed decision with the real tradeoffs understood matters more than winning the specific argument.

Beyond just operational reliability, a mature API platform function should be proactively identifying where API limitations are quietly constraining new partnership or product opportunities, and surfacing that before it becomes an urgent blocker on a critical initiative. I try to make sure the API platform is positioned as an enabler of what the business wants to build next, not only a function that keeps the lights on for what already exists.

Signals of needing fundamental change include chronic integration friction that never seems to reduce despite ongoing effort, a pattern of partner or internal integration failures traced back to the same underlying design inconsistencies repeatedly, or a structure that no longer matches how the business and its integration needs have evolved. I'd rather diagnose root causes honestly and propose real structural change when it's genuinely warranted than keep patching symptoms with incremental fixes that don't address the underlying gap.

I push for that knowledge to live in documented architecture decision records and a genuinely current API specification rather than only in people's heads, and I deliberately involve less senior engineers in API design discussions earlier than might feel comfortable so the reasoning spreads naturally through the team. Relying on a couple of people as the sole source of critical API design knowledge is a genuine organizational risk if either of them leaves.

I'd anchor the vision in where the business itself is heading over the next several years, projected partnership growth, new integration surfaces, then work backward to the platform capabilities that will need to be in place well before they become urgent. A vision built purely around adopting newer API technology for its own sake, disconnected from where the business is actually going, tends to lose leadership buy-in quickly.

I'd weigh how core and differentiating that specific capability is to the business against the ongoing cost and risk of building and maintaining deep in-house expertise for it. A capability that's central to the company's competitive advantage generally justifies in-house investment despite higher upfront cost, while a well-solved, commoditized problem, like basic rate limiting or API key management, is often better served by an established vendor solution.

I'd focus entirely on business outcomes, how API quality and reliability affect partnership velocity and revenue opportunities, and the cost of underinvestment measured in lost integration deals or partner churn, deliberately leaving out implementation detail that isn't relevant at that level. Board-level credibility comes from clear, confident framing of business impact, not from demonstrating technical depth that audience isn't positioned to evaluate.

I'd separate the immediate response, containing the damage and communicating transparently with affected partners, from the longer root-cause investigation, resisting pressure to assign blame before the actual cause is fully understood. Turning the postmortem into concrete, tracked process and governance changes matters more long-term than the specifics of any single incident.

I push for shared visibility into API quality and consumer satisfaction metrics rather than keeping that information siloed within the platform team, and I involve product engineering teams directly in setting the standards their own APIs will be held to. Recognizing and reinforcing that API quality is a shared responsibility, beyond something one central team alone is accountable for, changes how teams design their APIs in the first place.

I'd weigh how urgently a specific capability or fix is needed against how long building genuine internal expertise for it would realistically take, and how core that capability is to the business's long-term competitive position. An urgent, complex problem the team doesn't yet have deep expertise in usually favors bringing in outside help now, while something central and ongoing is worth the longer internal investment, even if it means moving more slowly at first.

I'd assess whether platform decision-making is currently too concentrated in one or two individuals to scale, whether the organizational structure still matches how the business has grown its integration surface, and whether the team has a genuine pipeline for developing the next generation of platform technical leaders. Proactively evolving the structure ahead of clear strain tends to go far better than waiting until the current structure has visibly broken under growth.