URI Path Design

Each URI path segment, separated by forward slashes (/), represents a design opportunity. Assigning meaningful values to each path segment helps to clearly communicate the hierarchical structure of a REST API’s resource model design.

• Rule: A singular noun should be used for document names

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio

• Rule: A plural noun should be used for collection names

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players00

• Rule: A plural noun should be used for store names

http://api.music.restapi.org/artists/mikemassedotcom/playlists

• Rule: A verb or verb phrase should be used for controller names

http://api.college.restapi.org/students/morgan/register

http://api.example.restapi.org/lists/4324/dedupe

• Rule: Variable path segments may be substituted with identity-based values. The URI template example below has three variables (leagueId,teamId, and playerId):

http://api.soccer.restapi.org/leagues/{leagueId}/teams/{teamId}/players/{playerId}

Resource Modeling in REST APIs

The URI path conveys a REST API’s resource model, with each forward slash separated path segment corresponding to a unique resource within the model’s hierarchy. For example, this URI design:

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet

This process is similar to the data modeling for a relational database schema or the classical modeling of an object-oriented system.

http://api.soccer.restapi.org/leagues/seattle/teams/treb
http://api.soccer.restapi.org/leagues/seattle/teams
http://api.soccer.restapi.org/leagues/seattle
http://api.soccer.restapi.org/leagues
http://api.soccer.restapi.org

In order to communicate a clear and clean resource model to its clients, a REST API should align each resource with only one of these archetypes. Like design patterns, the resource archetypes help us consistently communicate the structures and behaviors that are commonly found in REST API designs. A REST API is composed of four distinct resource archetypes: document, collection, store, and controller. For uniformity’s sake, resist the temptation to design resources that are hybrids of more than one archetype. Instead, consider designing separate resources that are related hierarchically and/or through links.

1. Document

A document resource is a singular concept that is akin to an object instance or database record. A document’s state representation typically includes both fields with values and links to other related resources Each URI below identifies a document resource:

http://api.soccer.restapi.org/leagues/seattle
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/mike

2. Collection

A collection resource is a server-managed directory of resources. Clients may propose new resources to be added to a collection. However, it is up to the collection to choose to create a new resource, or not. Resources can be grouped into collections. Each collection is homogeneous so that it contains only one type of resource, and unordered. Resources can also exist outside any collection. In this case, we refer to these resources as singleton resources. Collections are themselves resources as well. Each URI below identifies a collection resource:

http://api.soccer.restapi.org/leagues
http://api.soccer.restapi.org/leagues/seattle/teams
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players

3. Store

A store is a client-managed resource repository. A store resource lets an API client put resources in, get them back out, and decide when to delete them. On their own, stores do not create new resources; therefore a store never generates new URIs. Instead, each stored resource has a URI that was chosen by a client when it was initially put into the store. To insert a document resource named “Alex” in their store of favorites:

PUT /users/1234/favorites/alex

4. Controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Like a traditional web application’s use of HTML forms, a REST API relies on controller resources to perform application-specific actions that cannot be logically mapped to one of the standard methods.

Standard Methods: Create, Retrieve, Update, and Delete, also known as CRUD

POST /alerts/245743/resend

Controller names typically appear as the last segment in a URI path. 📷 SwapnIl Dwivedi

URI Design Rules for RESTful APIs

REST APIs use Uniform Resource Identifiers to address resources. It tells you how a site is organized. Best practices insist that the following rules have to be followed in order to maintain a common standard while designing URIs for APIs using REST architecture.

• Rule: Forward slash separator (/) must be used to indicate a hierarchical relationship.The forward slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources.
  • http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares
• Rule: A trailing forward slash (/) should not be included in URIs. A REST API must generate and communicate clean URIs and should be intolerant of any client’s attempts to identify a resource imprecisely. REST APIs should not expect a trailing slash and should not include them in the links that they provide to clients.
• Rule: Hyphens (-) should be used to improve the readability of URIs To make your URIs easy for people to scan and interpret,
• Rule: Underscores (_) should not be used in URIs. Text viewer applications (browsers, editors, etc.) often underline URIs to provide a visual cue that they are clickable.
• Rule: Lowercase letters should be preferred in URI paths. When convenient, lowercase letters are preferred in URI paths since capital letters can sometimes cause problems — URIs are case sensitive.
• Rule: File extensions should not be included in URIs. The best practice is to use headers in the HTTP request, which we will see about later on, to define the file types that are used

Below are the naming conventions to be used while designing the authority portion of a REST API.

• Rule: Consistent subdomain names should be used for your APIs. The top-level domain and first subdomain names (e.g., soccer.restapi.org) of an API should identify its service owner
• Rule: Consistent subdomain names should be used for your client developer portal. Many REST APIs have an associated website, known as a developer portal, to help onboard new clients with documentation, forums, and self-service provisioning of secure API access keys. If an API provides a developer portal, by convention it should have a subdomain labeled developer.

📷 Toa Heftiba

REST and APIs

Web services are purpose-built web servers that support the needs of a site or any other application. Client programs use application-programming interfaces (APIs) to communicate with web services. A Web API is the face of a web service, directly listening and responding to client requests. The REST architectural style is commonly applied to the design of APIs for modern web services. A Web API conforming to the REST architectural style is a REST API. Some best practices for REST API design are implicit in the HTTP standard, and consequentially present a set of REST API design rules that aim to provide clear and concise answers to the nagging questions arising while designing REST APIs.

Having a REST API makes a web service RESTful.

A REST API consists of an assembly of interlinked resources. HTTP was written standardizing these concerns and URI syntax, as we know it today. These constraints comprise the REST web architectural style. All of these rules were written to maintain a certain consistency while creating REST APIs. They also ensure that standards are established for developers to keep up with. By establishing these standards, we can make sure that future endeavors for development are fruitful, and they follow the best practices. 📷 Markus Spiske

The WorldWideWeb and REST

The “WorldWideWeb” was started by Sir Tim Berners Lee as a non-profit software project to share information among his peers. At the end of this project he had invented:

• The Uniform Resource Identifier (URI), a syntax that assigns each web document a unique address
• The Hypertext Transfer Protocol (HTTP).
• The Hypertext Mark-up Language (HTML).
• The first web server.
• The first web browser.
• The first WYSIWYG HTML editor, which was built right into the browser.

It was quite a breakthrough in the world of technology and continued to grow exponentially. As a result, the web traffic began to outgrow the capacity of the internet infrastructure. Additionally, the web’s core protocols were not uniformly implemented and they lacked support. With such rapid expansion, it was unclear if the Web would scale to meet the increasing demand.

In the early 90s, Roy Fielding analyzed the Web’s scalability problem and recognized the key governing constraints. He and others proposed a uniform approach that satisfies all of these constraints for the successful expansion of the Web. These constraints were grouped into six categories.

1. Client-server

• The web is a client-server based system in which clients and servers have discrete parts to play. Therefore, the separation of both is essential while maintaining independent implementations and uniform interfaces.

2. Uniform interface

• To establish the interaction standards between the Web’s components a uniform interface should exist between them. It is imperative in identifying and manipulating resources and hypermedia.

3. Layered system

• The need for network-based intermediaries such as proxies and gateways to be transparently deployed between a client and server using uniform interfaces. These are commonly used for security enforcement, response caching and load balancing.

4. Cache

• Caching is one of web architecture’s most important constraints because it reduces the overall cost of the Web. A cache may exist anywhere along the network path between the client and server. Caching response data can help to reduce client-perceived latency, increase the overall availability and reliability of an application, and control a web server’s load.

5. Stateless

• The stateless constraint dictates that a web server is not required to memorize the state of its client applications. As a result, each client must include all of the contextual information that it considers relevant in each interaction with the web server.

6. Code-on-demand

• Code-on-demand tends to establish a technology coupling between web servers and their clients, since the client must be able to understand and execute the code that it downloads on-demand from the server.

Finally, in the year 200, the Web’s scalability crisis was averted finally and the architectural style was given a name by Roy Fielding on his PhD dissertation. Thus, “Representational State Transfer (REST)” came into being.