RESTful API設計ベストプラクティス(8)

前のいくつかの文章はいくつかのRESTful APIの設計の方面の参考規範を紹介して、この文章は私達はいくつかの“不良”の例を見て、そして個人の実践の総括でこの一連のために終わります.皆さんのコメント交流を歓迎します.
一、いくつかの「不良」の例
1.現在のアクティブなステータスの問合せ

**   ：**
GET /activity/query?method=status&game=PDK&type=a
Accept:json 

**   ：**
{:status-code 200 
:body { status :       close/open}

コメント:rpcの風呂敷を外しただけで、ブラウザで直接調べることができますが、method=statusというフォーマットは典型的なrpcです.
2.プレイヤーはイベントギフトバッグを受け取る

**   ：**
POST /activity/package 
User-Agent:       
Cookie: token=XXXXXXXXXXXXXX 
Accept：application/json; charset=UTF-8 
Content-type: application/x-www-form-urlencoded; charset=UTF-8 
body: username=aa&name=”    ” 

**   ：**
{status-code: 201 //      
 body: { name : “    ” 
          msg : “*******”}}

コメント:(1)クライアントがデータを送信するには、アプリケーション/x-www-form-urlencodedフォーマットを選択し、より広く使用されているjsonまたはednフォーマットではありません.(2)あるプレイヤーにギフトバッグを追加するには、POST/activity/users/{user-id}/packages/{package-name}
3.局情報に基づいて対応する局ID(UUID)を検索する

**   ：**
GET /games/game-id/{qijuid}/{username}/{gamesign} 
Cookie: token=XXXXXXXXXXXXXX 

**   ：**
{status-code: 200 
        body: “fds4324324gfdfds324d /nil (    ，  nil)”

コメント:(1)ここで取得するリソースはgame-id、フィルタ条件はqijuid、username、gamesignなので、GET/games/game-id?qijuid={qijuid}&username={username}&game-sign={game-sign}. (2)game-idが存在しない場合はnilではなく404を返す.(3)特別な必要がなければJSONまたはEDNに一括して戻る.
4.1. 単局カード局の録画情報を取得する

**   ：**
GET /games/record/game-id 
Cookie: token=XXXXXXXXXXXXXX 
Accept：json 

**   ：**
{status-code: 200 
        body: {record: JKJKDJFSFDSJK…. //      }

4.2. 単局カード局の共有情報の取得

**   ：**
GET /games/game/game-id 
Cookie: token=XXXXXXXXXXXXXX 
Accept：json 

**   ：**
{status-code: 200 
body: {id:   ID 
       username:    ID 
       flower: 12345 
       time:      
       desc:          }}

コメント:カード局記録情報はカード局共有情報の1つの属性にすぎず、2つのインタフェースに分けて非RESTを取得する.リソース定義の場合、カード局というリソース(上記のすべての情報を含む)は外部に露出されるべきであり、1つのAPIで統一的に解決することができる.例えば、カード局のビデオを取得する:GET/super-star/games/:game-id?fields=record取得牌局所有分享情报:GET/super-star/games/:game-id
二、まとめ
総じて、現在、RESTful APIの設計とサービスの実現には、以下のいくつかの面で不足している可能性があります.

は、RPCの考え方でRESTful APIおよびRESTサービスを設計する.最も明らかな表現は、APIを設計する際に「XXに基づいてXXを得る」という習慣を使用することであり、これは典型的なRPC設計であり、リソースではなくプロセスに対するものである.

は「リソース」が抽象的にサービスするこのような形式を理解していない.また、リソースはプロシージャによって生成された値に対応します.

リソース関係のAPIを設計する場合、処理が正しくないので、上記の例を参照する.

クエリーパラメータをいつ使用するべきか、基本URIに「変数」をいつ書くべきかは不明です.

開発プロセスに問題があり、まず初歩的なAPI設計に基づいて、再実現し、さらにAPIを修正し、API設計が実現に妥協した.しかし、RESTサービスの実装は、テスト駆動開発と同様に、RESTful API駆動開発であるべきである.

APIの設計とRESTサービスは実現/現実に妥協している.

時間の圧力:本格的なRESTサービスを実現するには、その柔軟性と拡張性を実現するには、クエリーパラメータの柔軟な変動、カスタムソート、カスタムに必要なリソース属性など、RPC式の開発に比べて多くの時間がかかる可能性があります.

三、個人REST実践プロセスの総括
第一歩:リソース(RESTではリソースが粗粒度)を定義し、「リソース」を使用してサービス全体を抽象化します(リソースに違いありません!「何によって何を得るか」という考え方に陥らないでください!)、どのリソースが外部に露出する必要があるかを決定し、リソースの具体的な属性はまず細かく決定しないことができます.
第2ステップ:RESTful APIを設計し、第1ステップで定義したリソースを識別し、header(サポートされているメディアタイプ、content-typeなど)、bodyを含むリソース記述フォーマットを決定する.たとえば、クエリーパラメータによって自由にフィルタリングされるリソースがサポートされているか、返されるリソース属性が自由に指定されているか、リソース全体がすべて返されるリソースがサポートされているかを決定します.成功時のステータスコード、異常時のステータスコード、異常メッセージフォーマットなど.
ステップ3:APIについて実装します.