Google API 設計指南
https://cloud.google.com/apis/design?hl=zh-cn
也可以參考
https://choerodon.io/zh/docs/contributor-guide/development/conventions/restful/
设计流程
设计指南建议在设计面向资源的 API 时采取以下步骤（更多细节将在下面的特定部分中介绍）：
• 确定 API 提供的资源类型。
• 确定资源之间的关系。
• 根据类型和关系确定资源名称方案。
• 确定资源架构。
• 将最小的方法集附加到资源。
来自 <https://cloud.google.com/apis/design/resources>
URL命名（標準）
|
接口URL |
HTTP方法 |
接口说明 |
|
/article |
POST |
保存文章 |
|
/article |
GET |
查询文章列表 |
|
/article/{id} |
GET |
查询單個文章 |
|
/article/{id} |
DELETE |
删除文章 |
|
/article/{id} |
PUT |
更新文章信息 |
常用自定义方法
以下是常用或有用的自定义方法名称的精选列表。API 设计者在引入自己的名称之前应该考虑使用这些名称，以提高 API 之间的一致性。
|
方法名称 |
自定义动词 |
HTTP 动词 |
备注 |
|
取消 |
:cancel |
POST |
取消一个未完成的操作，例如 operations.cancel。 |
|
batchGet |
:batchGet |
GET |
批量获取多个资源。如需了解详情，请参阅列表描述。 |
|
移动 |
:move |
POST |
将资源从一个父级移动到另一个父级，例如 folders.move。 |
|
搜索 |
:search |
GET |
List 的替代方法，用于获取不符合 List 语义的数据，例如 services.search。 |
|
恢复删除 |
:undelete |
POST |
恢复之前删除的资源，例如 services.undelete。建议的保留期限为 30 天。 |
例如
|
/article/{id}:customVerb
|
POST or GET |
自定義方法 |
来自 <https://cloud.google.com/apis/design/custom_methods>
如果接口url有介詞應該怎麽辦？例如一個api目的是“dispatch express orders to ipad by date”
Url 命名要和class中method命名一一對應起來
class中method命名
|
动词 |
名词 |
方法名称 |
请求消息 |
响应消息 |
|
List |
Book |
ListBooks |
ListBooksRequest |
ListBooksResponse |
|
Get |
Book |
GetBook |
GetBookRequest |
Book |
|
Create |
Book |
CreateBook |
CreateBookRequest |
Book |
|
Update |
Book |
UpdateBook |
UpdateBookRequest |
Book |
|
Rename |
Book |
RenameBook |
RenameBookRequest |
RenameBookResponse |
|
Delete |
Book |
DeleteBook |
DeleteBookRequest |
google.protobuf.Empty |
来自 <https://cloud.google.com/apis/design/naming_convention>
Controller接受參數用VO
Input params format(命名為xxxxVO):
{
"addr_ref_value": "string",
"addr_type": "string",
"user": “”---create 操作的時候必須有，user id or staffCreate
"amend_date": "2020-10-12",
}
