🪛

REST API設計例

2024/08/04に公開

RESTful APIとは


RESTful APIは、Representational State Transfer (REST)の原則に従うウェブサービスの一形態です。RESTはウェブアーキテクチャスタイルを定義するアーキテクチャ原則および制約条件の集合であり、HTTPプロトコルを基盤としています。RESTful APIはこの原則を使用してクライアントとサーバー間の相互作用を単純かつ拡張可能にします。

RESTful API設計の主要原則

  1. クライアントとサーバーのアーキテクチャ
  2. ステートレスを維持
  3. キャッシュが可能ならばキャッシュする
  4. レイヤードシステムを使用する
  5. クライアントが望むソースを送る(任意)
  6. 統一インターフェース(Uniform Interface)⭐️
    → データ識別可能
    → クライアントが理解できるフォーマットで送る
    → サーバーから受け取ったデータをもとにどのようにリクエストすればいいか分かる
    → 応答データにはクライアントがどのように処理すればいいか分かる情報を含む
    → サーバーを利用する方法のURLリストがある

Web APIsデザイン

CRUD

RESTful APIは、リソースに対してCRUD(Create、Read、Update、Delete)の操作を実行できる必要があります。

RESTful API開発原則

識別できること

  • URLだけでどのリソースを操作しようとしているか分かる必要があります。リソースを操作するために、リソースの場所や種類を明確に表現する必要があります。
  • サーバーが提供する情報はJSONまたはXML形式でHTTPボディに含まれて送信されます。

行為は明示的であるべき

  • RESTはアーキテクチャまたは方法論に似ています。そのため、この方法を使わなければならないと強制されるわけではありません。従来のウェブサービスのように、GETを利用してUPDATEやDELETEを行うこともできます。
  • ただし、RESTアーキテクチャには適合しないため、RESTに従っているとは言えません。

自己記述的であるべき

  • データに関するメタ情報だけでどの種類のデータか、データを処理するためにどのアプリケーションを実行すべきかを分かる必要があります。つまり、データ処理のための情報を得るためにデータソースを読む必要がある場合は自己記述的ではありません。

REST API設計例

URIは動詞ではなく名詞を、大文字ではなく小文字を使用するべきです。

Bad Example http://sunnyheee/Running/
Good Example  http://sunnyheee/run/  

最後にスラッシュ(/)を含めない。

Bad Example http://sunnyheee/test/  
Good Example  http://sunnyheee/test

アンダースコアの代わりにハイフンを使用する。

Bad Example http://sunnyheee/test_blog
Good Example  http://sunnyheee/test-blog 

ファイル拡張子をURIに含めない。

Bad Example http://sunnyheee/photo.jpg  
Good Example  http://sunnyheee/photo  

行為を含めない。

Bad Example http://sunnyheee/delete-post/1  
Good Example  http://sunnyheee/post/1  

REST APIsについての詳細
https://www.ibm.com/jp-ja/topics/rest-apis
RESTに関するウィキペディアの記事
https://ja.wikipedia.org/wiki/Representational_State_Transfer

Good例

https://docs.github.com/ja/rest

Discussion