Home RESTful API: How to design paths and identify resources
Post
Cancel

RESTful API: How to design paths and identify resources

繼上篇文章RESTful API簡介: 什麼是RESTful? 以及為何需要它?後, 我們知道了RESTful API是resource based的,今天講著重討論該如何設計resource,也就是HTTP URL中path的部分。

Resource based

每個URL都應該對應到一個或多個資源,使用那些使用者與你的服務互動時會需要用到的資源(名詞), 並使用HTTP Method來表明你想要對資源的操作(動詞),比如說你是一個網誌服務, 使用者可以看、新增、修改、刪除自己的文章,也能瀏覽別的作者的文章,

1
2
3
4
5
6
7
8
GET     /articles               -> 看全部的文章
GET     /articles/d8e209        -> 看某篇文章
POST    /articles               -> 新增文章
PUT     /articles/4f8662        -> 修改某篇文章
DELETE  /articles/4f8662        -> 刪除某篇文章

GET     /authors/homuchen               -> 看作者homuchen的資訊
GET     /authors/homuchen/articles      -> 看作者homuchen的所有文章

將操作轉成名詞

如果你想要進行的操作比較複雜,可能是需要同時對多個資源進行操作,又或者是無法以CRUD之一來表示, 可以考慮自己創造一個新的Resource。

無法以CRUD表示

比如說你想要lock及unlock某篇文章,此時只有一個人可以讀取或修改它, HTTP Method裡沒有可以表示lock及unlock的操作,所以就自己創造一個資源叫article-locks, 並使用PUT、DELETE來操作。

1
2
PUT     /article-locks/{article_id}     -> Lock住某篇文章
DELETE  /article-locks/{article_id}     -> Unlock某篇文章

牽涉多個資源

當你的一個任務需要同時對多個資源進行操作時,有兩種做法,一個是讓client發出多個api請求, 另一個則是定義一個新的endpoint,來幫使用者做完所有的事。

比如說API的使用者想要發起一筆交易,需要從A帳戶扣一筆錢,在B帳戶新增一筆錢, 如果讓client自己送出兩個api請求也可以,但是他就要處理其他許多狀況,比如說其中一個api成功,另一個失敗怎麼辦。

1
2
3
4
#還要確保兩個api request同時成功或同時失敗

PUT     /accouts/A/withdrawal   -> 從A帳戶扣一筆錢
PUT     /accouts/B/deposit      -> 在B帳戶新增一筆錢

或者可以創造一個新的資源叫transaction,使用PUT來發起一筆交易,而api server則幫client處理了所有該注意的事, 使這個交易atomic、檢查A帳戶裡的餘額夠不夠等等…

1
PUT     /transactions   -> 發起一筆交易

Identify sub-resources via path segments

有些資源他本身可能沒有意義,也不會被直接使用,必須仰賴在某些資源下,才知道他所要代表的事物, 比如說文章底下的留言,如果不知道它們是在哪篇文章底下,留言本身就無法被看懂, 此時可以使用多段的path來表示parent-child的階層關係。

1
2
3
4
/articles                                       -> 所有文章
/articles/{article-id}                          -> 某篇文章
/articles/{article-id}/comments                 -> 某篇文章的所有評論
/articles/{article-id}/comments/{comment-id}    -> 每篇文章的某則評論

Summary

今天看了要如何設計我們API的URL,重點就是URL是資源、是名詞,搭配method,表示要對資源進行的操作, 當操作無法以CRUD表示、或需要同時對多個資源進行操作時,可以考慮創造新的domain entity。 另外當資料有階層性的關係時,可以使用多段的path還表示。

這是RESTful API一系列文章中的一篇,想了解更多關於RESTful API及HTTP的,可以看這篇目錄:

RESTful API Design — A practical guide

This post is licensed under CC BY 4.0 by the author.

[讀書筆記] 一週工作4小時: 擺脫朝九晚五的窮忙生活,晉身「新富族」!

RabbitMQ和Kafka有何不同?何時該選用哪種產品?

Comments powered by Disqus.