Restful API接口規(guī)范

簡(jiǎn)介

REST:英文representational state transfer直譯為表現(xiàn)層狀態(tài)轉(zhuǎn)移陈瘦,或者表述性狀態(tài)轉(zhuǎn)移胸梆;Rest是web服務(wù)的一種架構(gòu)風(fēng)格计维,一種設(shè)計(jì)風(fēng)格龄章,是一種思想吃谣;同時(shí)Rest不是針對(duì)某一種編程語(yǔ)言的。

以webService為例通俗解釋做裙。

非Rest設(shè)計(jì)岗憋,以往我們都會(huì)這么寫(xiě):

http://localhost:8080/admin/getUser (查詢(xún)用戶(hù))

http://localhost:8080/admin/addUser (新增用戶(hù))

http://localhost:8080/admin/updateUser (更新用戶(hù))

http://localhost:8080/admin/deleteUser (刪除用戶(hù))

總結(jié):以不同的URL(主要為使用動(dòng)詞)進(jìn)行不同的操作。

Rest架構(gòu):

GET http://localhost:8080/admin/user (查詢(xún)用戶(hù))

POST http://localhost:8080/admin/user (新增用戶(hù))

PUT http://localhost:8080/admin/user (更新用戶(hù))

DELETE http://localhost:8080/admin/user (刪除用戶(hù))

總結(jié):URL只指定資源锚贱,以HTTP方法動(dòng)詞進(jìn)行不同的操作仔戈。用HTTP STATUS/CODE定義操作結(jié)果。

Restful:遵守了rest風(fēng)格的web服務(wù)便可稱(chēng)為Restful拧廊。

為什么需要Restful监徘?

URL具有很強(qiáng)可讀性的,具有自描述性

規(guī)范化請(qǐng)求過(guò)程和返回結(jié)果

資源描述與視圖的松耦合

可提供OpenAPI吧碾,便于第三方系統(tǒng)集成凰盔,提高互操作性

提供無(wú)狀態(tài)的服務(wù)接口,降低復(fù)雜度滤港,可提高應(yīng)用的水平擴(kuò)展性

/版本號(hào)/資源路徑

/v1/tags/{tag_id}

/v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20]

1、版本號(hào)

命名版本號(hào)可以解決版本不兼容問(wèn)題趴拧,在設(shè)計(jì) RESTful API 的一種實(shí)用的做法是使用版本號(hào)溅漾。一般情況下,我們會(huì)在 url 中保留舊版本號(hào)著榴,并同時(shí)兼容多個(gè)版本

【GET】 /v1/users/{user_id} // 版本 v1 的查詢(xún)用戶(hù)列表的 API 接口

【GET】 /v2/users/{user_id} // 版本 v2 的查詢(xún)用戶(hù)列表的 API 接口

2添履、資源路徑

URI 不能包含動(dòng)詞,只能是名詞(命名名詞的時(shí)候脑又,要使用小寫(xiě)暮胧、數(shù)字及下劃線來(lái)區(qū)分多個(gè)單詞)锐借。

資源的路徑應(yīng)該從根到子依次如下:

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

【POST】 /v1/users/{user_id}/roles/{role_id} // 添加用戶(hù)的角色

有的時(shí)候,當(dāng)一個(gè)資源變化難以使用標(biāo)準(zhǔn)的 RESTful API 來(lái)命名往衷,可以考慮使用一些特殊的 actions 命名钞翔。

/{resources}/{resource_id}/actions/{action}

【PUT】 /v1/users/{user_id}/password/actions/modify // 密碼修改

3、請(qǐng)求方式

【GET】 /users # 查詢(xún)用戶(hù)信息列表

【GET】 /users/1001 # 查看某個(gè)用戶(hù)信息

【POST】 /users # 新建用戶(hù)信息

【PUT】 /users/1001 # 更新用戶(hù)信息(全部字段)

【PATCH】 /users/1001 # 更新用戶(hù)信息(部分字段)

【DELETE】 /users/1001 # 刪除用戶(hù)信息

【PATCH】一般不用席舍,用【PUT】

4布轿、查詢(xún)參數(shù)

RESTful API 接口應(yīng)該提供參數(shù),過(guò)濾返回結(jié)果来颤。

【GET】 /{version}/{resources}/{resource_id}?offset=0&limit=20

5汰扭、響應(yīng)參數(shù)

JSON格式(code、data福铅、msg)

6萝毛、狀態(tài)碼

使用適合的狀態(tài)碼很重要,而不應(yīng)該全部都返回狀態(tài)碼 200

狀態(tài)碼滑黔,可根據(jù)以下標(biāo)準(zhǔn)按照項(xiàng)目擴(kuò)展自身狀態(tài)碼:

200~299段 表示操作成功:

200 操作成功笆包,正常返回

201 操作成功,已經(jīng)正在處理該請(qǐng)求

300~399段 表示參數(shù)方面的異常

300 參數(shù)類(lèi)型錯(cuò)誤

301 參數(shù)格式錯(cuò)誤

302 參數(shù)超出正常取值范圍

303 token過(guò)期

304 token無(wú)效

400~499段 表示請(qǐng)求地址方面的異常:

400 找不到地址

500~599段 表示內(nèi)部代碼異常:

500 服務(wù)器代碼異常

7拷沸、完整事例
UserController.java

@RestController(/v1)

@API(tag=”用戶(hù)相關(guān)接口”)

public class UserController {
 

    @Autowired

    private UserJPARepository userJPARepository;


    /**

     * 查詢(xún)用戶(hù)列表

     * @return

     */

    @GetMapping(value = "/user")

    public List<User> findUserList(){

        return userJPARepository.findAll();

    }


    /**

     * 根據(jù)Id查詢(xún)一個(gè)用戶(hù)

     * @param id

     * @return

     */

    @GetMapping(value = "/user/query/{id}")

    public User findUserOne(@PathVariable("id") Integer id){

        return userJPARepository.findOne(id);

    }


    /**

     * 添加用戶(hù)

     * @param name

     * @param age

     * @param country

     * @return

     */


    @PostMapping(value = "/user")

    public User addUser(@RequestParam("name") String name, @RequestParam("age") int age,

                        @RequestParam("country") String country){

        User user = new User();

        user.setName(name);

        user.setAge(age);

        user.setCountry(country);

        return userJPARepository.save(user);

    }

    /**

     * 刪除用戶(hù)

     * @param id  用戶(hù)編號(hào)

     * @return

     */

    @DeleteMapping(value = "/user/{id}")

    public  List<User> deleteUser(@PathVariable("id") Integer id){

        userJPARepository.delete(id);

        return userJPARepository.findAll();

    }

    /**

     * 更新用戶(hù)

     * @param id

     * @param name

     * @param age

     * @param country

     * @return

     */

    @PutMapping(value = "/user/{id}")

    public User updateUser(@PathVariable("id") Integer id, @RequestParam("name") String name,

                           @RequestParam("age") int age, @RequestParam("country") String country){

        User user = userJPARepository.findById(id);

        user.setName(name);

        user.setAge(age);

        user.setCountry(country);

        return userJPARepository.save(user);

    }

    /**

     * 根據(jù)國(guó)家查詢(xún)用戶(hù)

     * @param country

     * @return

     */

    @GetMapping(value = "/user/{country}")

    public List<User> findByCountry(@PathVariable("country") String country){

        return userJPARepository.findByCountry(country);

    }

}
最后編輯于
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
  • 序言:七十年代末色查,一起剝皮案震驚了整個(gè)濱河市,隨后出現(xiàn)的幾起案子撞芍,更是在濱河造成了極大的恐慌秧了,老刑警劉巖,帶你破解...
    沈念sama閱讀 222,681評(píng)論 6 517
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件序无,死亡現(xiàn)場(chǎng)離奇詭異验毡,居然都是意外死亡,警方通過(guò)查閱死者的電腦和手機(jī)帝嗡,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 95,205評(píng)論 3 399
  • 文/潘曉璐 我一進(jìn)店門(mén)晶通,熙熙樓的掌柜王于貴愁眉苦臉地迎上來(lái),“玉大人哟玷,你說(shuō)我怎么就攤上這事狮辽。” “怎么了巢寡?”我有些...
    開(kāi)封第一講書(shū)人閱讀 169,421評(píng)論 0 362
  • 文/不壞的土叔 我叫張陵喉脖,是天一觀的道長(zhǎng)。 經(jīng)常有香客問(wèn)我抑月,道長(zhǎng)树叽,這世上最難降的妖魔是什么? 我笑而不...
    開(kāi)封第一講書(shū)人閱讀 60,114評(píng)論 1 300
  • 正文 為了忘掉前任谦絮,我火速辦了婚禮题诵,結(jié)果婚禮上洁仗,老公的妹妹穿的比我還像新娘。我一直安慰自己性锭,他們只是感情好赠潦,可當(dāng)我...
    茶點(diǎn)故事閱讀 69,116評(píng)論 6 398
  • 文/花漫 我一把揭開(kāi)白布。 她就那樣靜靜地躺著篷店,像睡著了一般祭椰。 火紅的嫁衣襯著肌膚如雪。 梳的紋絲不亂的頭發(fā)上疲陕,一...
    開(kāi)封第一講書(shū)人閱讀 52,713評(píng)論 1 312
  • 那天方淤,我揣著相機(jī)與錄音,去河邊找鬼蹄殃。 笑死携茂,一個(gè)胖子當(dāng)著我的面吹牛,可吹牛的內(nèi)容都是我干的诅岩。 我是一名探鬼主播讳苦,決...
    沈念sama閱讀 41,170評(píng)論 3 422
  • 文/蒼蘭香墨 我猛地睜開(kāi)眼,長(zhǎng)吁一口氣:“原來(lái)是場(chǎng)噩夢(mèng)啊……” “哼吩谦!你這毒婦竟也來(lái)了鸳谜?” 一聲冷哼從身側(cè)響起,我...
    開(kāi)封第一講書(shū)人閱讀 40,116評(píng)論 0 277
  • 序言:老撾萬(wàn)榮一對(duì)情侶失蹤式廷,失蹤者是張志新(化名)和其女友劉穎咐扭,沒(méi)想到半個(gè)月后,有當(dāng)?shù)厝嗽跇?shù)林里發(fā)現(xiàn)了一具尸體滑废,經(jīng)...
    沈念sama閱讀 46,651評(píng)論 1 320
  • 正文 獨(dú)居荒郊野嶺守林人離奇死亡蝗肪,尸身上長(zhǎng)有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
    茶點(diǎn)故事閱讀 38,714評(píng)論 3 342
  • 正文 我和宋清朗相戀三年,在試婚紗的時(shí)候發(fā)現(xiàn)自己被綠了蠕趁。 大學(xué)時(shí)的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片薛闪。...
    茶點(diǎn)故事閱讀 40,865評(píng)論 1 353
  • 序言:一個(gè)原本活蹦亂跳的男人離奇死亡,死狀恐怖俺陋,靈堂內(nèi)的尸體忽然破棺而出豁延,到底是詐尸還是另有隱情,我是刑警寧澤腊状,帶...
    沈念sama閱讀 36,527評(píng)論 5 351
  • 正文 年R本政府宣布诱咏,位于F島的核電站,受9級(jí)特大地震影響寿酌,放射性物質(zhì)發(fā)生泄漏胰苏。R本人自食惡果不足惜硕蛹,卻給世界環(huán)境...
    茶點(diǎn)故事閱讀 42,211評(píng)論 3 336
  • 文/蒙蒙 一醇疼、第九天 我趴在偏房一處隱蔽的房頂上張望硕并。 院中可真熱鬧,春花似錦秧荆、人聲如沸倔毙。這莊子的主人今日做“春日...
    開(kāi)封第一講書(shū)人閱讀 32,699評(píng)論 0 25
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽(yáng)陕赃。三九已至,卻和暖如春颁股,著一層夾襖步出監(jiān)牢的瞬間么库,已是汗流浹背。 一陣腳步聲響...
    開(kāi)封第一講書(shū)人閱讀 33,814評(píng)論 1 274
  • 我被黑心中介騙來(lái)泰國(guó)打工甘有, 沒(méi)想到剛下飛機(jī)就差點(diǎn)兒被人妖公主榨干…… 1. 我叫王不留诉儒,地道東北人。 一個(gè)月前我還...
    沈念sama閱讀 49,299評(píng)論 3 379
  • 正文 我出身青樓亏掀,卻偏偏與公主長(zhǎng)得像忱反,于是被迫代替她去往敵國(guó)和親。 傳聞我的和親對(duì)象是個(gè)殘疾皇子滤愕,可洞房花燭夜當(dāng)晚...
    茶點(diǎn)故事閱讀 45,870評(píng)論 2 361

推薦閱讀更多精彩內(nèi)容