REST Representational state transfer REST Resource Naming Guide Never use CRUD function names in URI

怎樣用通俗的語言解釋什麼叫 REST，以及什麼是 RESTful？ - 知乎 https://www.zhihu.com/question/28557115html

你們都知道"古代"網頁是前端後端融在一塊兒的，好比以前的PHP，JSP等。在以前的桌面時代問題不大，可是近年來移動互聯網的發展，各類類型的Client層出不窮，RESTful能夠經過一套統一的接口爲 Web，iOS和Android提供服務。另外對於廣大平臺來講，好比Facebook platform，微博開放平臺，微信公共平臺等，它們不須要有顯式的前端，只須要一套提供服務的接口，因而RESTful更是它們最好的選擇。前端

http://www.infoq.com/cn/articles/webber-rest-workflow?utm_source=infoq_en&utm_medium=link_on_en_item&utm_campaign=item_in_other_langsshell

"那麼，Web和REST之間究竟有什麼關係呢？咱們接下來將聊聊組成Web的幾大基礎技術，URI（統一資源標識符，用來標識資源）、HTTP（超文本傳輸/轉移協議，用來操做資源）、Hypertext（超文本，用來描述資源的內容與狀態，咱們能夠用HTML、XML、JSON或者自定義格式的文原本描述任何一個資源）安全

「跟大部分餐飲企業同樣，星巴克也主要致力於將訂單處理的吞吐量最大化。顧客訂單越多，收入就越多。爲此，他們採起了異步處理的辦法。你在點單時，收銀員取出一隻咖啡杯，在上面做上記號代表你點的是什麼，而後把這個杯子放到隊列裏去。這裏的隊列指的是在咖啡機前排成一列的咖啡杯。正是這個隊列將收銀員與咖啡師解耦開，從而，即使在咖啡師一時忙不過來的時候，收銀員仍然能夠爲顧客點單。他們能夠在繁忙時段安排多個咖啡師，就像競爭消費者模式（Competing Consumer）裏那樣。」

"Starbucks, like most other businesses is primarily interested in maximizing throughput of orders. More orders equals more revenue. As a result they use asynchronous processing. When you place your order the cashier marks a coffee cup with your order and places it into the queue. The queue is quite literally a queue of coffee cups lined up on top of the espresso machine. This queue decouples cashier and barista and allows the cashier to keep taking orders even if the barista is backed up for a moment. It allows them to deploy multiple baristas in a Competing Consumer scenario if the store gets busy."

REST Resource Identifier (URI) Naming – REST API Tutorial https://restfulapi.net/resource-naming/

REST Resource Naming Guide

In REST, primary data representation is called Resource. Having a strong and consistent REST resource naming strategy – will definitely prove your one of best design decisions in long term.

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. 「today’s weather in Los Angeles」), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time. Roy Fielding’s dissertation

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

A resource may contain sub-collection resources also. For example, sub-collection resource 「accounts」 of a particular 「customer」 can be identified using the URN 「/customers/{customerId}/accounts」 (in a banking domain). Similarly, a singleton resource 「account」 inside the sub-collection resource 「accounts」 can be identified as follows: 「/customers/{customerId}/accounts/{accountId}」.

REST APIs use Uniform Resource Identifiers (URIs) to address resources. REST API designers should create URIs that convey a REST API’s resource model to its potential client developers. When resources are named well, an API is intuitive and easy to use. If done poorly, that same API can feel difficult to use and understand.

The constraint of uniform interface is partially addressed by the combination of URIs and HTTP verbs, and using them in line with the standards and conventions.

Below are a few tips to get you going when creating the resource URIs for your new API.

REST Resource Naming Best Practices

Use nouns to represent resources

RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties as verbs do not – similar to resources have attributes. Some example of resource are:

Users of the system
User Accounts
Network Devices etc.

and their resource URIs can be designed as below:

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 more clarity, let’s divide the resource archetypes into four categories (document, collection, store and controller) and then you should always target to put a resource into one archetype and then use it’s naming convention consistently. For uniformity’s sake, resist the temptation to design resources that are hybrids of more than one archetype.

document

A document resource is a singular concept that is akin to an object instance or database record. In REST, you can view it as a single resource inside resource collection. A document’s state representation typically includes both fields with values and links to other related resources.

Use 「singular」 name to denote document resource archetype.
```
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
```
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. A collection resource chooses what it wants to contain and also decides the URIs of each contained resource.

Use 「plural」 name to denote collection resource archetype.
```
http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts
```
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. 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.

Use 「plural」 name to denote store resource archetype.
```
http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists
```
controller

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

Use 「verb」 to denote controller archetype.
```
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 formatting for minimum ambiguily and maximum readability and maintainability. You may implement below design hints to achieve consistency:

Use forward slash (/) to indicate a hierarchical relationships

The forward slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources. e.g.

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}

Do not use trailing forward slash (/) in URIs

As the last character within a URI’s path, a forward slash (/) adds no semantic value and may cause confusion. It’s better to drop them completely.
```
http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices 	/*This is much better version*/
```

Use hyphens (-) 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.

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

Do not use underscores ( _ )

It’s posible to use an underscore in place of hyphen to be used as seperator – But depending on the application’s font, it’s possible that the underscore (_) character can either get 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
```
Use lowercase letters in URIs

When convenient, lowercase letters should be consistently preferred in URI paths.

RFC 3986 defines URIs as case-sensitive except for the scheme and host components. e.g.
```
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 above examples, 1 and 2 are same but 3 is not as it uses My-Folder in capital letters.
Do not use file extenstions

File extensions look bad and do not add any advantage. Removing them decerase the length of URIs as well. No reason to keep them.

Apart from above reason, if you want to highlight the media type of API using file extenstion then you should rely on the media type, as communicated through the Content-Type header, to determine how to process the body’s content.
```
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*/
```

Never use CRUD function names in URIs

URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.

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

Use query component to filter URI collection

Many times, you will come across requirements where you will need a collection of resources sorted, filtered or limited based on some certain resource attribute. For this, do not create new APIs – rather enable sorting, filtering and pagination capabilities in resource collection API and pass the input parameters as query parameters. e.g.

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

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?

API designers, please note the following rules before calling your creation a REST API:

There are probably other rules that I am forgetting, but the above are the rules related to the hypertext constraint that are most often violated within so-called REST APIs. Please try to adhere to them or choose some other buzzword for your API.

REST – PUT vs POST – REST API Tutorial https://restfulapi.net/rest-put-vs-post/

REST – PUT vs POST

It has been observed that many people struggle to choose between HTTP PUT vs POST methods when designing a system. Though, RFC 2616 has been very clear in differentiating between the two – yet complex wordings are source of confusion for many of us. Lets try to solve the puzzle when to use PUT or POST.

Lets compare them for better understanding.

PUT	POST
RFC-2616 clearly mention that `PUT` method requests for the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource – an update operation will happen, otherwise create operation should happen if Request-URI is a valid resource URI (assuming client is allowed to determine resource identifier). PUT /questions/{question-id}	The `POST` method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. It essentially means that `POST` request-URI should be of a collection URI. POST /questions
`PUT` method is idempotent. So if you send retry a request multiple times, that should be equivalent to single request modification.	`POST` is NOT idempotent. So if you retry the request N times, you will end up having N resources with N different URIs created on server.
Use `PUT` when you want to modify a singular resource which is already a part of resources collection. PUT replaces the resource in its entirety. Use PATCH if request updates part of the resource.	Use `POST` when you want to add a child resource under resources collection.
`PUT` is idempotent, so you can cache the response.	Responses to this method are not cacheable, unless the response includes appropriate Cache-Control or Expires header fields. However, the 303 (See Other) response can be used to direct the user agent to retrieve a cacheable resource.
Generally, in practice, always use `PUT` for UPDATE operations.	Always use `POST` for CREATE operations.

PUT vs POST : An Example

Let’s say we are designing a network application. Let’s list down few URIs and their purpose to get better understanding when to use POST and when to use PUT operations.

GET 	/device-management/devices : Get all devices
POST 	/device-management/devices : Create a new device

GET 	/device-management/devices/{id} : Get the device information identified by "id"
PUT 	/device-management/devices/{id} : Update the device information identified by "id"
DELETE	/device-management/devices/{id} : Delete device by "id"

Follow the similar URI design practices for other resources as well.

Reference: SO Thread

PUT冪等

put update

post create

put update wholly

patch upate partly

https://help.aliyun.com/document_detail/31947.html



DELETE /?logging HTTP/1.1 Host: BucketName.oss-cn-hangzhou.aliyuncs.com Date: GMT Date Authorization: SignatureValue



DELETE /?logging HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 05:35:24 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:6ZVHOehYzxoC1yxRydPQs/Cn****

https://cloud.tencent.com/document/product/436/7749

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Object Content]

REST Representational state transfer REST Resource Naming Guide Never use CRUD function names in URI

REST Resource Naming Guide

REST Resource Naming Best Practices

Use nouns to represent resources

document

collection

store

controller

Consistency is the key

Use forward slash (/) to indicate a hierarchical relationships

Do not use trailing forward slash (/) in URIs

Use hyphens (-) to improve the readability of URIs

Do not use underscores ( _ )

Use lowercase letters in URIs

Do not use file extenstions

Never use CRUD function names in URIs

Use query component to filter URI collection

REST – PUT vs POST

PUT vs POST : An Example