Stop worrying about the name of the REST interface

REST resource naming Guide

In REST, the master data representation is called a resource. Have a strong and consistent REST resource naming strategy - it will certainly prove that you are one of the best design decisions in the long run.

The key abstraction of information in REST is a resource. Any information that can be named can be resources: documents or images, temporary services (such as "today's weather in Los Angeles"), collections of other resources, non virtual objects (such as people), and so on. In other words, any concept that may be the target of an author's hypertext reference must conform to the definition of a resource. A resource is a conceptual mapping to a set of entities, not entities corresponding to the mapping at any particular point in time. Roy Fielding's paper

A resource can be a single or a collection. For example, "customers" is a collection resource and "customer" is a singleton resource (in the banking domain). We can use the URI "/ customers" to identify the '' collection resource. We can use the URI "/ customers/{customerId}" to identify a single "" resource.

A resource may contain a subset of resources. For example, you can use URN "" (in the banking domain) to identify the subset resource "" / customers/{customerId}/accounts of accounts specific "customer". Similarly, the accounts of a single resource '' in the account subset resource '' can be identified as follows: "/ customers/{customerId}/accounts/{accountId}".

The REST API uses a uniform resource identifier (URI) to address resources. REST API designers should create URIs to communicate the resource model of the REST API to potential client developers. When resources are well named, the API is intuitive and easy to use. If you don't do it well, the same API will feel difficult to use and understand.

The constraint part of the unified interface is solved by the combination of URI and HTTP verbs, and they are used according to standards and conventions.

Here are some tips you can use when creating a resource URI for a new API.

REST resource naming best practices

Use nouns to denote resources

Restful URIs should refer to resources as things (nouns) rather than actions (verbs), because nouns have attributes that verbs do not have - similar to resources with attributes. Some examples of resources are:

  • Users of the system
  • User account
  • Network equipment, etc
    Their resource URI s can be designed as follows:
http://api.example.com/device-management/managed-devices 
http://api.example.com/device-management/managed-devices/{device-id} 
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}

For clarity, let's divide the resource prototype into four categories (document, collection, storage and controller), then you should always put the resource into a prototype, and then use its naming convention consistently. For the sake of consistency, resist the temptation of design resources, which are a mixture of more than one prototype.

1. document

Document resources are a single concept similar to object instances or database records. In REST, you can think of it as a single resource in a collection of resources. The status representation of a document typically includes fields with values and links to other related resources.

Use the singular name to represent the document resource prototype.

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

2. collection

A collection resource is a resource directory managed by the server. Customers can suggest adding new resources to the collection. However, it is up to the collection to choose whether to create a new resource. The collection resource selects what it wants to include and determines the URI of each included resource.

Use the plural name to represent the collection resource prototype.

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

3. store

The store is a repository managed by the client. Store resources allow API clients to put resources, exit them, and decide when to delete them. The store will never generate a new URI. Instead, each stored resource has a URI selected by the client when it was first placed in the store.

Use "plural" names to represent store resource prototypes.

http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists

4. controller

Controller resource simulator concept. Controller resources are like executable functions with parameters and return values; Input and output.

Use "verb" to represent the controller prototype.

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

Consistency is the key

Use consistent resource naming conventions and URI formats to minimize and maximize readability and maintainability. You can implement the following design tips for consistency:

1. Use the forward slash (/) to indicate the hierarchical relationship

The forward slash (/) character is used in the path part of the URI to indicate the hierarchical relationship between resources. for example

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

2. Do not use trailing slashes (/) in URI s

As the last character in the URI path, the forward slash (/) does not add a semantic value and may cause confusion. It's best to give them up completely.

http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices /This is much better version/

3. Use hyphen (-) to improve the readability of URI

To make your URI easy to scan and interpret, use hyphen (-) characters to improve the readability of names in long path segments.

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation //Less readable

4. Do not use underscores ()

You can use underscores instead of hyphens as separators - but depending on the font of your application, underscores () characters may be partially obscured or completely hidden in some browsers or screens.

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

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readable
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location //More error prone

5. Use lowercase letters in URI s

Lowercase letters should always be preferred in URI paths when convenient.

RFC 3986 defines URI s as case sensitive, with the exception of schema and host components. for example

http://api.example.org/my-folder/my-doc //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2
http://api.example.org/My-Folder/my-doc //3

In the above example, 1 and 2 are the same, but 3 is not because it uses my folder in uppercase letters.

6. Do not use file extensions

File extensions look terrible and do not add any advantage. Deleting them also reduces the length of the URI. There's no reason to keep them.

In addition to the above reasons, if you want to use the file extension to highlight the media type of the API, you should rely on the media type conveyed through the content type header to determine how to deal with the content of the body.

http://api.example.com/device-management/managed-devices.xml /Do not use it/
http://api.example.com/device-management/managed-devices /This is correct URI/

Do not use CRUD function names in URI s

The URI should not be used to indicate the execution of CRUD functions. URIs should be used to uniquely identify resources, not any operations on them. The HTTP request method should be used to indicate which CRUD function to perform.

HTTP GET http://api.example.com/device-management/managed-devices  //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices  //Create new Device

HTTP GET http://api.example.com/device-management/managed-devices/{id}  //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id}  //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id}  //Delete device for given Id

Filtering URI collections using query components

Many times, you will encounter the requirements of sorting, filtering or restricting the collection of resources according to some specific resource attributes. To do this, do not create a new API - instead, enable sorting, filtering and paging functions in the resource collection API, and pass the input parameters as query parameters. for example

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date

Original link

ps: markdown is very good

RESTful API

Tags: RESTful

Posted on Mon, 29 Nov 2021 13:58:44 -0500 by cordoprod

Hot Tags

©2022 Programmer Help