请求
最后更新于：2022-04-01 04:39:52
## 请求（Requests）
### 在请求的body体使用JSON格式数据
在 `PUT`/`PATCH`/`POST` 请求的正文（request bodies）中使用JSON格式数据，而不是使用 form 表单形式的数据。这与我们使用JSON格式返回请求相对应，例如:
~~~
$ curl -X POST https://service.com/apps \
-H "Content-Type: application/json" \
-d '{"name": "demoapp"}'
{
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "demoapp",
"owner": {
"email": "username@example.com",
"id": "01234567-89ab-cdef-0123-456789abcdef"
},
...
}
~~~
### 使用统一的资源路径格式
#### 资源名（Resource names）
使用复数形式为资源命名，除非这个资源在系统中是单例的 (例如，在大多数系统中，给定的用户帐户只有一个)。 这种方式保持了特定资源的统一性。
#### 行为（Actions）
好的末尾不需要为资源指定特殊的行为，但在特殊情况下，为某些资源指定行为却是必要的。为了描述清楚，在行为前加上一个标准的`actions`：
~~~
/resources/:resource/actions/:action
~~~
例如：
~~~
/runs/{run_id}/actions/stop
~~~
### 路径和属性要小写
为了和域名命名规则保持一致，使用小写字母并用`-`分割路径名字，例如：
~~~
service-api.com/users
service-api.com/app-setups
~~~
属性也使用小写字母，但是属性名要用下划线`_`分割，以便在Javascript中省略引号。 例如：
~~~
service_class: "first"
~~~
### 支持方便的无id间接引用
在某些情况下，让用户提供ID去定位资源是不方便的。例如，一个用户想取得他在Heroku平台app信息，但是这个app的唯一标识是UUID。这种情况下，你应该支持接口通过名字和ID都能访问，例如:
~~~
$ curl https://service.com/apps/{app_id_or_name}
$ curl https://service.com/apps/97addcf0-c182
$ curl https://service.com/apps/www-prod
~~~
不要只接受使用名字而放弃了使用id。
### 最小化路径嵌套
在一些有父路径/子路径嵌套关系的资源数据模块中，路径可能有非常深的嵌套关系，例如:
~~~
/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}
~~~
推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源。在上述例子中，dyno属于app，app属于org可以表示为：
~~~
/orgs/{org_id}
/orgs/{org_id}/apps
/apps/{app_id}
/apps/{app_id}/dynos
/dynos/{dyno_id}
~~~