restfull api

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",

}