This document discusses custom methods in web APIs. Some key points covered include: 1. Custom methods are API calls that fall outside standard HTTP methods and are used to express actions that don't fit within standard methods. 2. Custom methods should use a verb-noun format separated by a colon, like POST /missiles/:launch, and can have side effects unlike standard methods. 3. Custom methods may target single resources or collections, and can be used for complex actions like communicating with other systems during a state transition. 4. While useful, custom methods also introduce challenges to maintaining REST principles in an API. Trade-offs between framework fit and flexibility should be considered.

1. Part 3 Fundamentals
9. Custom methods
Rick Hwang
2022/04/20
1

2. How to safely support these actions on resources in a web
API while maintaining a simple, predictable, and functional
API using what we’ll call custom methods.
2

3. Recap
3

4. 9.1 Motivation
1. when we need the ability to express a specific action that doesn’t really fit
very well in one of the standard methods (ch7).
2. how to integrate to current systems or framework:
○ should we try to jam the behavior we want into the existing methods, bending the framework a
bit to fit our needs? Or
○ should we change our behavior into a form that fits a bit more cleanly within the framework?
Or
○ should we change the framework to accommodate our new scenario?
4

5. 1
2.1
2.2
5

6. Two resources:
1. EmailDraft
2. Email
---
6

7. 1. most state changes are transitions of some sort or another, and as a result,
transitioning to a new state is fundamentally different from setting the value of
a scalar field.
a. This field feels like it should be managed by the API service itself rather than updated by the
client.
b. 狀態 (State) 的改變 (transition) 應該由 Service 管理，不是 POST 過來
2. As we learned in chapter 7, standard methods really should NOT do anything
besides the specific action their name implies.
7

8. 9.2 Overview
Custom methods are nothing
more than API calls that fall
outside the scope of a standard
method.
8

9. 9.3 Implementation
1. 不要使用 farword slash (/) 作動詞區隔，像是 POST /rockets/1234567/launch (這很重
要)
a. Rick: 哪裡重要？
2. RPC 遵循規則： 動詞 + 名詞，像是 LaunchRocket or ArchiveDocument，避免使用 With / For 等
介系詞。
9

10. 10

11. 11

12. 9.3.1 Side Effects
Standard Methods
1. 針對能操作的資源，提供 有限制的機制
2. Standard Method 之外，沒有其他行為 (理
論上)
Custom Methods
1. 針對能操作的資源，提供 有彈性的機制
2. 依照 Standard Method 的行為之外，可以
表述其他行為，像是 觸發 額外的背景操作
舉例：1) CreateEmail -> 2) SendEmal
12

13. 5.1 Load EmailDraft
from Storage
使用 Custom Method:
處理複雜的行為，像是與另外
的系統通訊 (SMTP)
同時處理 Resources and
Collections
使用 Standard Method:
單純、簡單
13

14. 9.3.2 Resources vs Collections
某一個人的某一
封 Email
某一個人的全部
14

15. 匯出單一 User 的所有 Email (General Users),
or
一個操作執行多個資源操作:
ex: 使用一個 API 匯出一堆 Email (Admin)
以下都是匯出多個資源。。。
1) POST /users/1:exportEmails
2) POST /users/1/emails:export
3) POST /users/1:export
哪個好？
更多參
閱
Ch23
15

16. 針對跨 Users 的 Email 進行操作，像是 archive / export
● users/1/emails/2:export
● users/2/emails/4:export
使用 hyphon 當作 Wildcard 代表使用者。
POST /users/-/emails:export
{
“1”: [2],
“2”: [4],
}
更多參
閱
Ch23
16

17. 9.3.3 Stateless
custom methods
17

18. Stateful custom
methods
18

19. 9.4 Trade-offs
the very existence of these custom methods tends to present a contradiction (矛
盾) with REST and the principles underpinning RESTful API design.
19

20. Summary
1. Custom methods should almost always use the HTTP POST method and never use the
PATCH method. They might use the GET method if the custom method is idempotent and
safe.
2. Custom methods use a colon (:) character to separate the resource target from the action
being performed (e.g., /missiles/1234:launch).
3. While side effects are forbidden for standard methods, they are permitted for custom
methods. They should be used sparingly and documented thoroughly to avoid confusion for
users.
4. In general, custom methods should target a collection when multiple resources from a
single collection are involved.
5. Sometimes, particularly for computational work, APIs might choose to rely on stateless
custom methods to perform the bulk of the work. This strategy should be used cautiously as
it’s easy for statefulness to eventually become important and can be difficult to introduce
later on.
20