7 rules for REST API URIs

 

Before delving into the conventions of REST API URIs, let's briefly review the terminology.

 

  

 

URI

 

REST APIs use URLs. In today's web, URI design ranges from masterpieces that clearly communicate an API's resource model to those that are difficult for people to understand.

 

Tim Berners Lee made a note about the opacity of URIs in his list of "Principles of Web Architecture".

"The only thing you can use an identifier for is referencing an object. When not dereferencing, see the contents of the URI string for other information."

 

Clients must follow the linking paradigm of the web and treat URIs as incomplete identifiers.

 

REST API designers must create URIs that convey the REST AP's resource model to potential client developers.

In this post,  I would like to introduce some design rules for REST API URIs .

 

Before looking at conventions, the conventions presented in this section pertain to the word URI format. RFC 3986 defines generic URI syntax as follows:

 

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

 

 

---

 

rule 1

The trailing slash (/) must not be included in the URI

 

This is one of the most important rules that must be followed as the final character in determining the URI path. The forward slashes are meaningless and can be confusing. REST APIs require that the trailing slash should not be included in the API URL passed to the client developer.

 

Many web components or frameworks treat the following two URIs identically.

http://moretranslate.co.kr/moretranslate

http://moretranslate.co.kr/moretranslate/

 

However, all characters in the URI are included in the resource's unique ID.

 

2 different URIs map to 2 different resources. If the URI is different, the resource is also different. So REST APIs should generate and pass clean and unambiguous URIs. Also, you must not tolerate any attempts by clients to access incorrectly.

This is because clients, our development partners, are not the only targets of API calls.

 

 

 

 

 

rule 2

A forward slash separator (/) must be used to indicate hierarchical relationships.

 

The slash character is used to indicate a hierarchical relationship between resources in the path portion of a URI.

Example:  http://board.com/board/52  -> Post #52 of the board.

 

 

 

 

 

 

rule 3

Use the hyphen (-) character to improve the readability of URIs.

 

Use hyphen characters to make the URIs you define easier for people to read. You must use hyphens in URIs wherever spaces or hyphens are used in English.

To make your URI easier for people to scan and interpret, use the hyphen (-) character to improve the readability of names in long path segments. You must use hyphens in URIs wherever spaces or hyphens are used in English.

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

 

 

 

 

 

 

rule 4

Do not use the underscore (_) character in URIs.

 

Text viewer programs (browsers, editors, etc.) often underline URIs to indicate that they are clickable. Depending on the program's font, underscore (_) characters may be partially or completely hidden by these underscores.

 

To avoid this confusion, it is recommended to use the hyphen (-) character instead of the underscore (_).

 

 

 

 

 

 

rule 5

Lowercase letters are appropriate for composing URIs

 

It is recommended to use lowercase letters when composing URIs because uppercase letters sometimes cause problems. RFC 3986 defines URIs as case sensitive, excluding scheme and host components. Capitalization can cause problems, so it is recommended to use lower case for URI paths when convenient.

 

yes :

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

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

The URI above is fine. The URI format specification (RFC 3986) considers this URI the same as URI #1.

 

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

This URI is not the same as URIs 1 and 2, which can lead to unnecessary confusion.

 

 

 

 

 

 

 

rule 6

Do not include file extensions in URIs

 

On the web, a dot (.) is used to separate the filename and extension of a URI. REST APIs MUST NOT include these file extensions in their URIs to indicate the body format of the message entity body. Instead, the media type, as passed through a header called Content-Type, should be used to determine how to handle 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 represent formats.

 

REST API clients are encouraged to use the Accept request header, which is the format selection mechanism provided by HTTP.

 

To enable simple linking and debugging, the REST API can support media type selection via a query string parameter.

 

 

 

 

 

 

rule 7

Usually URIs are written in English. Should the written English be singular? Should it be plural?

 

The simple retention rule applies here. You might think it's wrong to mark a single instance as plural, but it's common practice to use the plural form of a URI. The simple retention rule applies here. Your inner grammarian will tell you that using the plural to describe a single instance of a resource is incorrect, but the pragmatic answer is to keep the URI format consistent and always use the plural.

 

It's easier for API consumers to use and API providers to implement without having to deal with weird plurals (like person/people) (most modern frameworks have to specify between /students (plural) and /students/232324 (plural)). ) processed in the form

 

But how to deal with relationships? When relationships can only exist within other resources, the RESTFUL principle provides useful guidance. For example, one student has several courses. These courses are mapped to /students as follows:

 

http://api.college.com/students/3248234/courses  Retrieves a list of all courses studied by the student with ID 3248234

http://api.college.com/students/3248234/courses/physics  Search for course physics for student with ID 3248234.

conclusion

When designing a REST API  service  , you need to pay close attention to the resources defined by their URIs.

Each resource in the service will be identified by at least one URI. It's best when a specific URI adequately describes the resource. URIs should be predictable and hierarchical to improve understandability and usability. In other words, it is predictable in terms of being consistent, and hierarchical in that data has structure.

RESTFul APIs are written for consumers. The name and structure of a URI must convey meaning to its consumers. By following the rules above, you can create a much cleaner REST API with a much happier client. This is not a mandatory constraint. However, you can improve the API by following the rules above.

* This content   is based on https://dzone.com/articles/7-rules-for-rest-api-uri-design-1 .

7 Rules for REST API URI Design - DZone Integration

URIs, or Uniform Resource Identifiers, should be designed to be readable and clearly communicate the API resource model. These rules will help you succeed.

dzone.com