Seven rules designed by the REST API URI
These seven simple rules will help you write readable, conflict-free URIs that convey all the necessary resource information.
Mr Levin
Before exploring the rules for REST API URI design, let’s quickly summarize some of the terms we’ll be discussing.
URIs
The REST API uses the Uniform Resource Identifier (URI) to address resources. In today’s network, URI design ranging from clear, such as the resources of the API model masterpiece, http://api.example.com/louvre/leonardo-da-vinci/mona-lisa, for those who are more difficult for people to know, Such as http://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66.
Tim Berners-Lee includes a note about the opacity of URIs in his list of “Web Architecture Axioms” : “The only identifiers that can be used are reference objects. You should not look at the contents of the URI string for additional information without dereferencing it.”
Clients must follow the Web’s linking paradigm and treat URIs as opaque identifiers.
REST API designers should create URIs to communicate the REST API’s resource model to potential client developers. In this article, I’ll try to introduce a set of design rules for the REST APIURI.
Before diving into these rules, the text on URI formatting in this section has to do with the format of URIs. RFC 3986 defines the generic URI syntax as follows:
URI = scheme “://” authority “/” path [ “?” query ] [ “#” fragment ]
Rule 1
The URI should not contain a trailing forward slash (/).
This is one of the most important rules to follow, because the last character in the URI path, the forward slash (/), does not add semantic value and can cause confusion. REST APIs should not contain slashes, nor should they include them in the links they provide to clients.
Many Web components and frameworks treat the following two URIs equally:
http://api.canvas.com/shapes/
http://api.canvas.com/shapesHowever, each character in the URI counts toward the unique identity of the resource.
Two different URIs map to two different resources. If the URI is different, the resource is different, and vice versa. Therefore, REST APIs must generate and pass clean URIs, and should not tolerate any attempts by clients to misidentify a resource.
More permissive APIs can redirect clients to URIs without trailing backslashes (they might also return 301 — “permanently moved” for relocating resources).
Rule 2
The forward slash delimiter (/) must be used to indicate a hierarchical relationship.
The path portion of the URI uses the forward slash (/) character to indicate a hierarchical relationship between resources. For example: http://api.canvas.com/shapes/polygons/quadrilaterals/squares
Rule 3
A hyphen (-) should be used to improve the readability of URIs.
To make your URIs easy for people to scan and interpret, use a hyphen (-) to improve the readability of names in long path segments. Anywhere you use a space or a hyphen in English, you should use a hyphen in the URI.
For example: http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post
Rule 4
The underscore (_) should not be used in URIs.
Text viewer applications (browsers, editors, and so on) typically underline URIs to provide clickable visual prompts. Depending on the font of the application, the underscore (_) character may be partially masked or completely hidden by this underscore.
To avoid this confusion, use a hyphen (-) instead of an underscore.
Rule 5
Lowercase letters should be preferred in URI paths.
It is best to use lowercase letters in URI paths when it is convenient, because uppercase letters can sometimes cause problems. RFC 3986 defines URIs as case sensitive, except for schema and host components.
Such as:
1) 2) http://api.example.com/my-folder/my-doc http://api.example.com/my-folder/my-docThe URI above is good. The URI format specification (RFC 3986) considers this URI to be the same as URI # 1.
3) http://api.example.com/My-Folder/my-doc
This URI is different from URI 1 and URI 2, which can lead to unnecessary confusion.
Rule 6
File extensions should not be included in URIs.
On the Web, the period (.) The character is typically used to separate the filename and extension parts of a URI. The REST API should not include a human file extension in the URI to indicate the format of the entity body of the message. Instead, they should rely on the media Type conveyed via the Content-Type header to determine how to handle the body Content.
http://api.college.com/students/3248234/courses/2005/fall.json
http://api.college.com/students/3248234/courses/2005/fallFile extensions should not be used to indicate format preferences.
REST API clients should be encouraged to take advantage of the format selection mechanism provided by HTTP, namely the Accept Request header.
For easy linking and debugging, the REST API can support media type selection through query parameters.
Rule 7
Should the endpoint name be singular or plural?
The keep it simple rule applies here. Although an internal grammar expert will tell you that it is wrong to use plurals to describe a single instance of a resource, the pragmatic answer is to be consistent with the format of the URI and always use plurals.
Not having to deal with irregular plurals (person/people, goose/geese) makes API consumers’ lives better, Is implemented for API providers (e.g., the most modern frameworks handle /students and /students/3248234 easily via controllers).
But how do you handle relationships? If the relationship could only exist in another resource, then RESTful principles would provide useful guidance. Let’s look at an example. A student has many classes. These courses are logically mapped to the /students endpoint, as follows:
http://api.college.com/students/3248234/courses – retrieve the ID of 3248234 students to learn a list of all courses. http://api.college.com/students/3248234/courses/physics – retrieve the ID of 3248234 students of the physical course.
conclusion
When designing REST API services, you must be mindful of resources. These are defined by URIs.
Each resource in one or more services that you are building will have at least one URI that identifies it. Preferably, the URI makes sense and adequately describes the resource. URIs should follow a predictable hierarchy to enhance understandable, and thus usability: predictable in the sense of uniformity, and hierarchical in the sense that the data is structurally related.
RESTful APIs are written for consumers. The name and structure of the URI should convey meaning to these consumers. By following the above rules, you will use a happier client to create a cleaner REST API. This is not a REST rule or constraint, but it enhances the API.
I also suggest you take a look at these guidelines.
Design for your customers, not your data.