7 common API design interview questions (with answers!)

Questions about good REST API design are part of almost every job interview you will ever have as a back end or full stack developer. It's important to understand the core concepts of REST and how to apply them when designing APIs for real-life use cases. To freshen up your memory and help you prepare for your next job interview, I have collected the most common API design interview questions that I have come across in my career:

Question 1: What is a RESTful API?

A RESTful API is an application program interface (API) that is based on representational state transfer (REST), an architectural style for designing web services. In REST, standard HTTP methods are used for creating, reading, updating and deleting resources.‍

Question 2: What is a resource in REST?

A resource can be any piece of information that can be named, e.g. a document, an image or a function. In REST, each resource is uniquely addressed by a Uniform Resource Identifier (URI).

Resources can be singletons (e.g. {% c-line %}/customers/:customerId{% c-line-end %}) or collections (e.g. {% c-line %}/customers{% c-line-end %}). Any resource can again hold sub-collection of resources (e.g. {% c-line %}/customers/:customerId/accounts{% c-line-end %}).

Question 3: What are the architectural constraints of REST?

Client-server architecture: The user interface is separated from data storage which enables easier portability of the user interface across platforms and simplifies scaling server components.

Statelessness: No client context is being stored on the server between requests. Each client request holds all necessary information for the server to fulfill the request, including session state.

Cacheability: Server responses are marked as either cacheable or non-cacheable. Cacheable responses can reduce server-client communication for further similar requests.

Uniform interface: The four constraints for uniform interfaces are:‍

1. Resource identification in requests: Individual resources are identified in requests, e.g. through URIs. Resource representations returned from the server (e.g. JSON, XML) are independent from the internal representation (e.g. database entry).‍
2. Resource manipulation through representations: With the representation of a resource, the client has enough information to update or delete a resource.
3. ‍Self-descriptive messages: Each response holds enough information for a client to know how to process it (e.g. through media type headers).‍
4. Hypermedia as the engine of application state (HATEOAS): After accessing an initial URI, clients should be able to use server-provided links to discover all other available resources it needs.

Layered system: REST APIs can be composed of hierarchical components, no component can see beyond the other component that it immediately interacts with.

Code-on-demand (optional): Servers can temporarily customize the functionality of a client by transferring executable code.

Question 4: Which HTTP methods are used in REST and what are their purposes?

• GET: Requests a resource representation. Should be cacheable.
• POST: Creates a new resource. Should return the URI of the created resource.
• PUT: Updates or replaces an existing resource.
• PATCH: Modifies an existing resource. Only needs to contain changes, not the whole resource.
• DELETE: Deletes a resource.
• OPTIONS: Requests available communication methods.
• HEAD: Requests resource metadata without retrieving the full resource representation.

Question 5: What is the difference between POST and PUT?

POST: Creates a new resource. It is not idempotent, that means for multiple invocations with the same request body, multiple new resources with unique identifiers will be created.

PUT: Updates or replaces an existing resource. It is idempotent, that means multiple invocations with the same request body have the same effect as a single invocation: the resource will be updated afterwards.

Question 6: What are best practices for naming resources?

• Use plural nouns to address resources, e.g. {% c-line %}/playlists{% c-line-end %} for a collection of playlists. For resources that act like functions, use verbs (e.g. {% c-line %}/playlists/:playlistId/play{% c-line-end %}).
• Use hyphens when separating long resource names. Don't use spaces as they'll be encoded as {% c-line %}%20{% c-line-end %} and avoid underscores since they are sometimes not fully visible depending on the font.
• Only use lowercase letters in URIs. Except for the protocol and host parts, URIs are case-sensitive, e.g. {% c-line %}/customers{% c-line-end %} and {% c-line %}/Customers{% c-line-end %} do NOT refer to the same resource. Consistently using lowercase letters prevents ambiguity.
• Do not use file extensions in resource names. Instead of using file extensions in resource names (e.g. {% c-line %}/users.json{% c-line-end %}), the {% c-line %}Content-Type{% c-line-end %} header should be supported to retrieve resource representations in different formats.
• Do not use HTTP operation names in resource names, e.g. prefer {% c-line %}/pets{% c-line-end %} over {% c-line %}/get-pets{% c-line-end %}.

Question 7: How should collection resources be filtered?

It is best considered practice to use query parameters to filter resources. Instead of exposing filter functionality as a separate resource, e.g.  {% c-line %}/users/filter-by-country {% c-line-end %}, use query parameters e.g.  {% c-line %}/users?country=us {% c-line-end %}.

‍