三、 RESTFUL API & laravel (part1) - amattsuyolo/cham GitHub Wiki

參考文章

心智圖內容將會不定期更新

API相關的介紹見參考文章或心智圖，

HTTP回傳狀態碼 API回傳的結果，應使用適當的HTTP狀態碼，所以API設計者必須了解它們。以下是一些常用的狀態碼，完整列表請參考Wikipedia。

2xx: 成功

    200 OK: 通用狀態碼
    201 Created: 資源新增成功
    202 Accepted: 請求已接受，但尚在處理中
    204 No Content: 請求成功，但未回傳任何內容

3xx: 重新導向

    301 Moved Permanently: 資源已移至它處
    303 See Other: 回傳的內容可在它處取得（例如在用戶端發送了一個POST請求之後）
    304 Not Modified: 請求的資源並未修改（通常是用戶端發送了帶有If-Modified-Since或If-None-Match表頭的請求）

4xx: 用戶端錯誤（用戶端不應retry原始請求）

    400 Bad Request: 通用狀態碼
    401 Unauthorized: 用戶端尚未驗證*
    403 Forbidden: 用戶端被禁止此請求*
    404 Not Found: 請求的資源不存在
    405 Method Not Allowed: 不支援請求的HTTP方法
    406 Not Acceptable: 不支援請求所要求的內容類型*（Accept表頭）
    415 Unsupported Media Type: 不支援請求所用的內容類型*（Content-Type表頭）

5xx: 伺服器錯誤（用戶端可合理retry）

    500 Internal Server Error: 工程師要找bug了
    501 Not Implemented: 用戶端的請求目前未支援（也就是將來有可能支援）
    502 Bad Gateway: 上游的伺服器未回傳正確結果，一般是gateway或proxy server才會回傳此狀態碼
    503 Service Unavailable: 暫停服務（也就是過不久就會恢復服務──如果一切順利的話）
    504 Gateway Timeout: 上游的伺服器逾時，一般是gateway或proxy server才會回傳此狀態碼

對於API的下列三個部分

Resource：資源。

Representational：表現形式。

State Transfer:狀態變化。利用HTTP動詞

依造個人經驗會遇到部分更新時

如刪除多個撥放紀錄，路由可能是:

localhost/watchrecord/batch verb use delete

或遇到每日登入獎勵搭配連續五天登入獎勵規則

需要同時增加虛擬幣、更改領取狀態、判斷連續天數，此類複雜情形路由相對難以按造restful 風格設計:

LARAVEL 相關輔助整理

資源控制器

當我們需要建立一個影片控制器，專門掌控影片的所有動作如 :

  1. 顯示所有
  2. 儲存
  3. 顯示單個
  4. 更新
  5. 刪除

可以下以下指令

    laravel 指令 php artisan make:controller api/VideosController --api

不需要自行註冊每一個路由

只需要一行程式碼:

    Route::resource("videos","api\VideosController");

產生對應的路由名稱與方法如下

          Actions Handled By Resource Controller

          Verb	URI	Action	Route Name

          GET	/videos	index	videos.index

          POST	/videos	store	videos.store

          GET	/videos/{video}	show	videos.show

          PUT/PATCH	/videos/{video}	update	videos.update

          DELETE	/videos/{video}	destroy	videos.destroy

如果僅僅需要顯示所有與儲存功能，路由部分可以調整如下

  Route::resource('videos', 'VideosController')->only([
      'index', 'store'
  ]);

或是

  Route::resource('photos', 'PhotoController')->except([
      'show', 'update', 'destroy'
  ]);

API Resource

當你在建立一個 API 時，可能會需要一個位於 Eloquent 模型和實際回傳給使用者的 JSON 回應之間的轉換層。Laravel 的資源類別可以讓你更直觀且容易的將你的模型和模型集合轉換成 JSON。

https://laravel.com/docs/5.8/eloquent-resources

API Resource 最大的優點是解耦了數據格式與業務代碼的耦合，提高了代碼的複用性和可維護性，更多功能可以參考官方文檔，這些都只是帶你入門，更多功能的使用和發掘，有賴你在實踐中去探尋。

個人認為良好的應用response()->json(["msg"=>"success","data"=>["video_id"=>"2000121",.......])即可解決大部分問題，將回傳數據格式分離，對於不夠巨大的專案有點過度設計的味道 https://laravel.com/docs/5.8/responses

後續持續更新.........