Service API Design - API Naming Specification

API naming convention

naming style

---

resource oriented

Same as RESTful naming style

In large-scale systems, modules are often divided from the perspective of "business domain" to achieve the effect of "high cohesion and low coupling" of business.

"Business domain" must have "data objects" precipitation, 从宏观抽象的角度看，"数据对象"可统称为"资源""business domain" is a collection of "resources" similar to business.

"资源"一定是业务抽象后的对象：

1. Can be a concrete data object:
   • merchandise
   • Order
   • contract
   • bill
   • Shopping list
   • etc
2. Can be an abstract object concept:
   • tenant
   • user
   • pay
   • document
   • need
   • etc

"业务领域"与"业务领域"之间的依赖，可理解为是对"资源"操作(读、写、通知)的依赖。

所以，API作为"业务领域"间沟通的手段，其应该(Should)以面向资源角度进行命名。

Note: Sub-resources need to be named by index, for example: Modify-Order-Item: updateOrderItem.

---

single point of view

• see Single Perspective Principle

---

verb-object style

The API should start with "动宾短语"风格命名.

E.g:

1 2 3 4 5

xxx.xxx.xxx.OrderService // Context already covers Order semantics Response<T> save(...) Response<T> updateItem(Long orderId, List<T> items)

1 2 3 4 5 6 7

xxx.xxx.xxx.WCService // Context does not cover Order semantics Response<T> saveOrder(...) Response<Boolean> removeOrder(Long orderId) Response<T> updateOrderItem(Long orderId, List<T> items) // Index sub-resources step by step

---

unified terminology

API naming unifies "verb" terms, "noun" terms. The advantage is that it can be consistent in style and experience reuse.

For details, please refer to Zhengcai Cloud API Terminology Reference

Note: The rhythm of unified terminology is gradually implemented with reference to the R&D-level terminology specification: unified within the business, unified within the business field, and unified on the platform.

Wrong practice-1: "Commodity" naming is not uniform

1 2 3 4

Business 1: Commodities -> item ✔️ Business 2: Commodities -> items Business 3: Commodities -> product Business 4: Commodities -> goods

Bad practice-2: "Features" are not named uniformly

1 2 3

Business 1: feature -> feature ✔️ Business 2: feature -> character Business 3: feature -> rule

Wrong practice-3: "Amount" is not named uniformly

1 2 3

Business 1: Amount -> amount ✔️ Business 2: Amount -> money Business 3: Amount -> sum

Wrong practice-4: "Check" naming is not uniform

1 2 3

Business 1: Verify -> verify Business 2: Verify -> check ✔️ Business 3: Verify -> test

Wrong practice-5: "Pagination" naming is not uniform

1 2 3

Business 1: Paging -> page Business 2: Paging -> paging✔️ Business 3: Paging -> list

Wrong practice-6: "create" naming is not uniform

1 2 3

Business 1: Create -> save✔️ Business 2: Create -> create Business 3: Create -> insert

Bad practice-7: "Delete" naming is inconsistent

1 2 3 4

Business 1: delete -> delete Business 2: delete -> remove✔️ Business 3: delete -> disable Business 3: delete -> cancel

Wrong practice-8: "Retrieval" naming is not uniform

1 2 3

Business 1: Search -> query✔️ Business 2: Search -> search Business 3: Search -> list

---

Common API naming reference

Assumption: The case where the Service is not divided by resources (the context does not define the resource domain)

"XXX" refers to a certain resource, and "xxx" refers to sub-resources under "XXX"

Paging query

• correct practice

1	Response<Page<T>> pagingXXX(QueryDTO q) //Wrap query conditions with objects

• wrong practice

1	Response<Page<T>> pagingXXX(String name, String code, Long orgId, Long creatorId, Integer pageNo, Integer PageSize)

Disadvantages of the above wrong practice:
1. For the caller, no matter what conditions are used to query, they need to pass parameters one by one.
2. The API is not friendly to expansion. Once you want to add query conditions, the API is incompatible.

List query

• correct practice

1	Response<List<T>> listXXX(...)

Get individual details

• correct practice

1 2 3 4 5

Response<T> getXXX(Long id) is similar to the condition, use overloaded Response<T> getXXX(String code)

• wrong practice

1 2 3

Response<T> getXXXById(Long id) Response<T> getXXXByCode(String code)

illustrate:

1. The API contract should be composed of "API name + input parameters", instead of just relying on "API name" to explain everything.
2. The API method supports the method of obtaining a single detail, which can be explained by the input field name. There is no need to use "By***" to mark additionally.
3. Methods without "By***" declarations are semantically more extensible.

create

• correct practice

1	Response<T> saveXXX(...) //Refer to "Alibaba Java Coding Specification"

delete

• correct practice

1	Response<T> removeXXX(...) //Refer to "Alibaba Java Coding Specification"

renew

• correct practice

1 2 3

Response<T> updateXXX(...) //参照《阿里巴巴Java编码规范》 Response<T> updateXXXxxx(...) //更新主资源下的子资源

提审

• 正确实践

1	Response<T> submitXXX(...)

审核

• 正确实践

1	Response<T> auditXXX(...)

退回（退回到流程中的某一步）

• 正确实践

1	Response<T> returnXXX(...)

撤销（退回到流程的第一步）

• 正确实践

1	Response<T> cancelXXX(...)

{{o.name}}

{{m.name}}