DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

The software you build is only as secure as the code that powers it. Learn how malicious code creeps into your software supply chain.

Apache Cassandra combines the benefits of major NoSQL databases to support data management needs not covered by traditional RDBMS vendors.

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Related

  • A Look at REST API Design Patterns
  • Design, Develop, Deploy and Manage a RESTful Application With MuleSoft
  • Surprisingly Simple Tools to Help You Smash API-First Approach
  • RAML vs. OAS: Which Is the Best API Specification for Your Project?

Trending

  • Memory Leak Due to Time-Taking finalize() Method
  • Infrastructure as Code (IaC) Beyond the Basics
  • The Full-Stack Developer's Blind Spot: Why Data Cleansing Shouldn't Be an Afterthought
  • Integrating Model Context Protocol (MCP) With Microsoft Copilot Studio AI Agents
  1. DZone
  2. Software Design and Architecture
  3. Integration
  4. 7 Rules for REST API URI Design

7 Rules for REST API URI Design

These seven simple rules will help you write readable, conflict-free URIs that communicate all necessary resource information.

By 
Guy Levin user avatar
Guy Levin
·
Updated Oct. 27, 23 · Opinion
Likes (30)
Comment
Save
Tweet
Share
81.7K Views

Join the DZone community and get the full member experience.

Join For Free

Before going over the rules for REST API URI design, let’s do a quick overview on some of the terms we are going to talk about.

URIs

REST APIs use Uniform Resource Identifiers (URIs) to address resources. On today’s web, URI designs range from masterpieces that clearly communicate the API’s resource model, to those that are much harder for people to understand.

Tim Berners-Lee included a note about the opacity of URIs in his “Axioms of Web Architecture” list: "The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information."

Clients must follow the linking paradigm of the Web and treat URIs as opaque identifiers.

REST API designers should create URIs that convey a REST API’s resource model to its potential client developers. In this post, I will try to introduce a set of design rules for REST API URIs. Learn how to secure a REST API with Keycloak, or how to secure REST APIs with client certificates.

Prior diving to the rules, a word about the URI Format as the rules presented in this section pertain to the format of a URI. RFC 3986 defines the generic URI syntax as shown below:

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

Rule #1

A trailing forward slash (/) should not be included in URIs.

This is one the most important rules to follow as the last character within a URI’s path, a forward slash (/) adds no semantic value and may cause confusion. REST API’s should not expect a trailing slash and should not include them in the links that they provide to clients.

Many web components and frameworks will treat the following two URIs equally:
http://api.canvas.com/shapes/
http://api.canvas.com/shapes

However, every character within a URI counts toward a resource’s unique identity.

Two different URIs map to two different resources. If the URIs differ, then so do the resources, and vice versa. Therefore, a REST API must generate and communicate clean URIs and should be intolerant of any client’s attempts to identify a resource imprecisely.

More forgiving APIs may redirect clients to URIs without a trailing forward slash (they may also return the 301 – “Moved Permanently” that is used to relocate resources”).

Rule #2

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. For example: http://api.canvas.com/shapes/polygons/quadrilaterals/squares

Rule #3

Hyphens (-) should be used to improve the readability of URIs.

To make your URIs easy for people to scan and interpret, use the hyphen (-) character to improve the readability of names in long path segments. Anywhere you would use a space or hyphen in English, you should use a hyphen in a URI.

For example: http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

Rule #4

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. Depending on the application’s font, the underscore (_) character can either get partially obscured or completely hidden by this underlining.

To avoid this confusion, use hyphens (-) instead of underscores.

Rule #5

Lowercase letters should be preferred in URI paths.

When convenient, lowercase letters are preferred in URI paths since capital letters can sometimes cause problems. RFC 3986 defines URIs as case-sensitive except for the scheme and host components.

For example:
1) http://api.example.com/my-folder/my-doc

2) HTTP://API.EXAMPLE.COM/my-folder/my-doc 

The above URI is fine. The URI format specification (RFC 3986) considers this URI to be identical to URI #1.

3) http://api.example.com/My-Folder/my-doc

This URI is not the same as URIs 1 and 2, which may cause unnecessary confusion.

Rule #6

File extensions should not be included in URIs.

On the Web, the period (.) character is commonly used to separate the file name and extension portions of a URI. A REST API should not include artificial file extensions in URIs to indicate the format of a message’s entity body. Instead, they should rely on the media type, as communicated through the Content-Type header, to determine how to process the body’s content.

http://api.college.com/students/3248234/courses/2005/fall.json
http://api.college.com/students/3248234/courses/2005/fall

File extensions should not be used to indicate format preference.

REST API clients should be encouraged to utilize HTTP’s provided format selection mechanism, the Accept request header.

To enable simple links and easy debugging, a REST API may support media type selection via a query parameter.

Rule #7

Should the endpoint name be singular or plural?

The keep-it-simple rule applies here. Although your inner grammatician will tell you it's wrong to describe a single instance of a resource using a plural, the pragmatic answer is to keep the URI format consistent and always use a plural.

Not having to deal with odd pluralization (person/people, goose/geese) makes the life of the API consumer better and is easier for the API provider to implement (as most modern frameworks will natively handle /students and /students/3248234 under a common controller).

But how do you deal with relations? If a relation can only exist within another resource, RESTful principles provide useful guidance. Let's look at this with an example. A student has a number of courses. These courses are logically mapped to the /students endpoint as follows:

http://api.college.com/students/3248234/courses - Retrieves a list of all courses that are learned by a student with id 3248234.
http://api.college.com/students/3248234/courses/physics - Retrieves course physics for a student with id 3248234.

Conclusion

When you are designing REST API services, you have to pay attention to resources; those are defined by URIs.

Each resource in a service or services you are building will have at least one URI identifying it. It's best when that URI makes sense and adequately describes the resource. URIs should follow a predictable, hierarchical structure to enhance understandability and, therefore, usability: predictable in the sense that they're consistent, hierarchical in the sense that data has structure—relationships.

RESTful APIs are written for consumers. The name and structure of URIs should convey meaning to those consumers. By following the above rules, you will create a much cleaner REST APIs with a much happier client. This is not a REST rule or constraint, but it enhances the API.

Design for your clients, not for your data.

Uniform Resource Identifier REST Web Protocols API Design

Published at DZone with permission of Guy Levin, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • A Look at REST API Design Patterns
  • Design, Develop, Deploy and Manage a RESTful Application With MuleSoft
  • Surprisingly Simple Tools to Help You Smash API-First Approach
  • RAML vs. OAS: Which Is the Best API Specification for Your Project?

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!