API Interview Questions and Answers: REST, API Gateway, and Design

API gateway interview questions

The gateway questions are the most common in system design loops, because a gateway is where most cross cutting concerns live.

What is an API gateway?

A gateway is a single entry point in front of many backend services. A client makes one call to the gateway, and the gateway routes it to the service that can answer it.

What does a gateway actually do?

• Routing. It maps a path or a host to a backend service.
• Authentication. It checks the caller once, so every service does not repeat it.
• Rate limiting. It caps how often a client can call, and returns 429 when they go over.
• Aggregation. It can call several services and merge the results into one response.
• Protocol translation. It can accept REST from a browser and speak gRPC to the backend.
• Observability. It is the one place that sees every request, so it is where you attach a request id.

How is a gateway different from a load balancer?

A load balancer spreads traffic across identical copies of one service. It works at the connection or request level and does not care what the request means.

A gateway understands the request. It reads the path, the method, and the headers, and decides which different service should handle it. It also does auth, rate limiting, and aggregation, which a load balancer never does.

Most real systems use both. The load balancer sits in front of the gateway instances.

How is a gateway different from a reverse proxy?

A reverse proxy forwards requests to a backend and can cache, terminate TLS, and compress. A gateway is a reverse proxy with API specific features on top: per route auth, rate limits, request shaping, and aggregation.

What are the downsides of a gateway?

It is a single point of failure, so it needs to be replicated. It adds a network hop, so it adds latency. It can become a shared bottleneck if teams keep pushing business logic into it. That last one is the answer interviewers want, because it is the failure they have seen.

What is the backend for frontend pattern?

Instead of one gateway serving every client, you run one per client type. The mobile gateway returns compact payloads. The web gateway returns richer ones. Each is owned by the team that owns that client, so nobody negotiates a shared response shape.

API design interview questions

Design the API for a payment system.

Start with the resources, not the endpoints. Payments, refunds, customers, and payment methods. Then the operations on each.

POST   /v1/payments              Charge a customer
GET    /v1/payments/{id}         Read one payment
POST   /v1/payments/{id}/refund  Refund it
POST   /v1/customers             Create a customer

Then raise the three things that make it a payment API rather than a CRUD API. Retries must not double charge, so accept an idempotency key. Some payments are slow, so decide between returning 202 with a webhook and blocking for the result. Errors need machine readable codes, because a client has to branch on insufficient_funds.

How do you version an API?

Version only when a change would break a working client. Adding an optional field is not breaking. Removing a field is. Put the major version in the path, so /v1/orders, and route on it at the gateway. Publish a support window and send Deprecation and Sunset headers before you retire anything.

How do you paginate a large collection?

Offset pagination takes a page number, and gets slower the deeper you go, because the database reads and discards skipped rows. Cursor pagination takes a pointer to the last item, stays fast at any depth, and does not duplicate rows when new ones arrive. Use cursor for feeds and logs, offset for small admin tables.

How do you design errors?

Return the right status code, then a body with a stable machine readable code and a human readable message.

{ "error": { "code": "insufficient_funds", "message": "The card has insufficient funds.", "field": "amount" } }

The code is the contract. The message is for humans and can change.

How do you make an API idempotent?

The client generates a unique key and sends it on the write, usually as an Idempotency-Key header. The server stores the key with the result. If the same key arrives again, it returns the stored result instead of doing the work twice.

REST, SOAP, GraphQL, and gRPC

REST versus SOAP. SOAP is a protocol with a strict XML envelope and a formal contract file. REST is a style using plain HTTP, usually with JSON. SOAP still appears in banking and telecom, where its built in standards for security and transactions are required.

REST versus GraphQL. REST gives you a fixed response per endpoint. That causes over fetching, which means receiving fields you do not need. It also causes under fetching, which means several calls to fill one screen. GraphQL gives clients one endpoint and lets them ask for exactly the fields they want. The cost is that caching is harder, and an expensive query can hurt the server. Add query depth and complexity limits.

REST versus gRPC. gRPC uses HTTP/2 and Protocol Buffers, a binary format defined by a schema. It is faster and generates client code, and it supports streaming. It does not work directly in a browser. The usual split is gRPC between internal services and REST at the public edge.

API security and authentication

How do you secure an API? Use HTTPS everywhere. Authenticate with OAuth 2.0 or signed tokens rather than passwords on each call. Give tokens the narrowest scope that works. Validate every input on the server. Rate limit per client. Never put a token in a query string, because query strings land in logs.

OAuth versus JWT. They are not alternatives. OAuth 2.0 is a framework for getting a token on a user's behalf. A JWT is one format that token can take. You can use OAuth and receive a JWT, and you can use JWTs with no OAuth at all.

What is CORS? Browsers block a page on one origin from reading a response from another origin. Cross Origin Resource Sharing is the set of response headers a server sends to allow specific origins. It is a browser rule, so it protects users, not your server.

API integration questions

These come up for roles that consume third party APIs.

How do you handle a third party API that fails? Retry with exponential backoff and jitter, so every client does not retry at the same instant. Wrap the call in a circuit breaker that fails fast after repeated errors. Have a fallback response so your own screen still renders.

How do you handle their rate limits? Read the X-RateLimit-Remaining and Retry-After headers and slow down before you are cut off. Queue non urgent calls. Cache anything that does not change often.

How do you keep data in sync? Prefer webhooks over polling. A webhook is a call they make to you when something changes, so you find out immediately and waste no requests. Verify the signature on every webhook, and make your handler idempotent, because they will retry.

API testing questions

Testing questions come up mostly for QA and platform roles.

API testing checks the interface directly instead of through a screen. It is faster than UI testing and less brittle, because it does not break when a button moves. The usual layers are:

• Functional tests per endpoint.
• Contract tests that check the response shape against the schema.
• Integration tests across services.
• Load tests for throughput.
• Security tests for auth and injection.

Common tools are Postman and Insomnia for exploring, REST Assured and pytest for automation, and JMeter or k6 for load. Contract testing tools such as Pact catch the case where a producer changes a field and a consumer breaks.