## 请求(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} ~~~