ホーム / WEB API /

フロントエンド技術を学ぼう 2-22.Web APIデザインについて学ぶ

2020年7月27日月曜日

Front-end Developer Handbook JavaScript WEB API

t f B! P L

Front-end Developer Handbook 2017を教科書にフロントエンド周りの技術を習得する連載。

第32回はPart II: Learning Front-End Devから、22項のLearn Data (i.e. JSON) API Designを紹介します。

Web APIデザインについて学ぶの説明です。


Web APIデザインについて学ぶ

Web APIとは、一般的にWebブラウザとサーバ間やサーバ同士の間でデータの送受信を行うためのインターフェースのことです。具体的にはHTTPプロトコルを用い、ここ数年はRESTを使用してJSON形式のデータをやり取りするスタイルが主流です。

参照元 :


REST

Representational State Transfer (REST) は、複数のソフトウェアを連携させるための考え方です。以下の4つの原則があります。

  • 全ての情報は一意なアドレス(URI)を持っている。
  • HTTPをベースに、ステートレスな情報のやり取りを行う。(セッションを持たない)
  • 情報の内部に、別の情報へのリンクを含めることができる。
  • 情報操作は全てHTTPメソッド(GET / POST / PUT / DELETE)を利用する。

これらの原則に沿ってつくられたAPIをRESTful APIと呼んだりします。これを採用することで以下の4つのメリットがあります。

  • URIに規律が生まれる。(管理性)
  • ブラウザからリソースの参照ができる。(接続性)
  • 負荷を抑え、スケーラビリティが向上する。(可用性)
  • HTTP標準メソッドにより、インターフェース操作が統一される。(操作性)

実際のWeb APIデザイン

実際にはRESTの原則に従いつつも、細かい仕様については自分で決めていかなければなりません。そこで、@veesahni氏のBest Practices for Designing a Pragmatic RESTful API(現実的なRESTfulAPIデザインのベストプラクティス)(日本語訳)にそって学んで行くのが近道だと思います。各項目に分けて、配慮すべき点を以下にまとめました。


設計

  • RESTfulなURL設計にする。
    (例: GET /tickets/12/messages/5)
  • 可能な限りJSONで返す。
  • JSON はgzip圧縮かつPrettyPrintで返す。

管理

  • 仕様書を作る。
    (WebページかつPDF以外のもの)
  • APIのバージョンはURLに含める。
    (例: /v1/tickets/12/messages/5)
  • フィールドの命名規則を考える。
    (スネークケースがベター)

リクエスト

  • フィルタ/ソート/検索はリクエストパラメータで行う。
    (例: GET /tickets?q=return&state=open&sort=-priority,created_at)
  • レスポンスのフィールドを絞れるようにする。
    (例: GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at)
  • GET/POSTしか使用できないクライアント用に、HTTP メソッドを上書き手段を用意する。
    (リクエストヘッダX-HTTP-Method-Overrideの使用)
  • 追加/更新時のリクエストボディにはJSONを使う。

レスポンス(JSON)

  • 作成/更新の後は変更後の情報をフルで返す。
  • 要素はラップせずに返す。
    (参照: CORS)
  • ページング情報はレスポンスヘッダに入れる。
    (Linkヘッダの使用)
  • 関連データを埋め込む手段を作る。
    (例: GET /tickets/12?embed=customer.name,assigned_user <- チケットID12の情報にcustomer.nameとassigned_userの関連情報を埋め込む。)
  • リクエスト制限情報をRFC 1123日付フォーマットに従い、レスポンスヘッダに入れる。

セキュリティ

  • SSL通信を使う。
  • トークン認証を使おう。
    (BASICまたはOAuth2認証)

その他

  • キャッシュの情報をレスポンスヘッダに入れる。
    (ETagまたはLast-Modified)
  • ちゃんとしたエラーメッセージを返す。
  • HTTP ステータスコードを有効活用する。

参照元 :


書籍

RESTful Web API Design with Node.JS - Second Edition(Node.JSを使用したRESTful Web APIデザイン)


QooQ