HTTPとREST APIについて調べた

マイクロサービスアーキテクチャでREST APIを作ったので
REST APIやHTTPついて色々調べたことをまとめておく。

実際に実装する場合については
Pythonの軽量フレームワークであるflaskを使ったREST APIの実装方法を
下記記事で紹介しています

【Docker × Flask】コンテナでFlask製のREST APIを実装する~基本~

Pythonのフレームワークであるflaskの開発環境をコンテナで構築し、VScodeからコンテナ内でflask製の基本的なREST APIを実装、動作させる方法をまとめる

REST APIとは？

REST APIとはWeb APIの一つで REST（Representational State Transfer）の原則に基づいて設計されたAPIのこと。
REST APIではリクエストのHTTPメソッドとURIでデータを操作する

RESTの4つの設計原則

RESTには4つの原則があり、この原則を満たしているAPIがREST APIになる。

統一インターフェース（Uniform Interface）

情報の操作(取得、作成、更新、削除)は全てHTTPメソッド(GET、POST、PUT、DELETE)を利用すること。
インターフェースが統一されていればブラウザ・JavaScriptコード・モバイルアプリケーションなど
RESTを利用するクライアントであれば同じ方法でサーバーが呼び出せ、リソースにアクセスができるようにする。

アドレス可能性（Addressability）

提供する情報がURIを通して表現できること。
全ての情報はURIで表現される一意なアドレスを持っていること。

接続性（Connectability）

情報の内部に、別の情報や(その情報の別の)状態へのリンクを含めることができること。

ステートレス性（Stateless）

HTTPをベースにしたステートレスなクライアント/サーバプロトコルであること。
セッション等の状態管理はせず、やり取りされる情報はそれ自体で完結して解釈できること。

URLとURIとエンドポイントとは？

REST APIのURL,URI,エンドポイントについて例えば

https://scrawledtechblog.com/blog?flg=true&id=3

を詳しく見てみる。
分解すると

• https: ：使用するプロトコル
• scrawledtechblog.com：リソースを保持していいるホストまたはドメイン
• blog ：リソースが保持されているホスト内のパス(パスパラメータ)
• flg=true&id=3 :クエリパラメータ

になる。

これをURL,URI,エンドポイントにわけると下記のようになる。

URL

クエリパラメータまで全てを含んだ

• https://scrawledtechblog.com/blog?flg=true&id=3

がURL。

URI

パスパラメータまでを含み、クエリパラメータを含まない

• https://scrawledtechblog.com/blog

がURI。

エンドポイント

URIと同じくパスパラメータまでを含み、クエリパラメータを含まない

• https://scrawledtechblog.com/blog

がエンドポイント。

URIとエンドポイントは文脈や使われ方によって変わるので曖昧だが
個人的に同じものとして理解している

厳密にはURIとエンドポイントは異なる概念らしいが、文脈として同じものを指すこともあるらしい。
なるほど。。。わからん

エントリーポイントとエンドポイントの違いは？

REST APIを調べていると

• エンドポイント
• エントリーポイント

という言葉をよく見かけたので、ちょっと調べてみた

エンドポイント

エンドポイントはAPI連携するためのURIのこと。 ユーザー視点。

REST APIにおけるエンドポイントの分け方について

REST APIでは、エンドポイントはリソースごとに分けて設計する。
この「リソースごと」というのは、パスパラメータまで含めてエンドポイントと考えるのが一般的。

たとえば

• /users はユーザーの一覧というリソース
• /users/123 はIDが123のユーザーという特定のリソース

このように、リソースの階層や関係性をURIで表現し、
パスパラメータを使って個別リソースを指定する。

パスパラメータの役割

パスパラメータは、リソースを一意に特定したいときに使う。
例：/blogs/1 → IDが1のブログを取得する。
※パスパラメータについては後述する

クエリパラメータの役割

クエリパラメータは、リストの絞り込みや検索、並び替え、ページングなどに使う。
例：/blogs?category=tech&page=2 → techカテゴリの2ページ目のブログ一覧を取得。
※クエリパラメータについては後述する

API設計の基本のポイント

• エンドポイントはリソース単位、パスパラメータまで含めて考える
• 「どのリソースか」を示すのがパスパラメータ
• 「どう取得するか（条件や並び）」を示すのがクエリパラメータ

エントリーポイント

エンドポイントと同じ。
視点をAPI公開側にした場合にエントリーポイントと呼ばれる。

REST APIと通常APIとの違い

大きく違うのはエンドポイントのURIの決まり方が異なる。

通常のAPIの場合

フロントエンドとバックエンドに別れたSPAのシステムの場合
例えばデータに対する処理のURIは下記のようになることが多い。

登録処理

登録処理をする場合のURI
https://scrawledtechblog.com/blog/registArticle

参照処理

参照処理をする場合のURI
https://scrawledtechblog.com/blog/getArticle

更新処理

更新処理をする場合のURI
https://scrawledtechblog.com/blog/updateArticle

削除処理

削除処理をする場合のURI
"ttps://scrawledtechblog.com/blog/deleteArticle

上記のように処理自体にURIが紐づく形になる。

REST APIの場合

通常APIに対して、REST APIは処理に対しては紐づかず、
リソースに対してURLが決まる。

たとえばREST APIの場合、エンドポイントとなるURIは
以下のように表現される。

https://scrawledtechblog.com/blog

この場合、このURIはblogというリソースに対する処理であることがわかる。

ただ、これだけだと何の処理をするのかはわからないので、
「何をするか」をHTTPメソッドで指定する必要がある。

つまり、REST APIでは処理を

• エンドポイント（URI） → どのリソースに対する操作か
• HTTPメソッド → そのリソースに対して何をするのか

の組み合わせで判断する。

REST APIは、「リソース志向」で、処理の内容はHTTPメソッドに任せる。
URIには動詞は使わず名詞を使うのが基本。
下記のような感じで、URIとHTTPメソッドの組み合わせで処理を表現するのがREST APIの考え方。

登録処理

HTTPメソッド：POST
URL 　　　　：https://scrawledtechblog.com/blog

参照処理

HTTPメソッド：GET
URL　　　　 ：https://scrawledtechblog.com/blog

更新処理

HTTPメソッド：PUT
URL　　　　 ：https://scrawledtechblog.com/blog

削除処理

HTTPメソッド：DELETE
URL　　　　 ：https://scrawledtechblog.com/blog

HTTPリクエストとは？

HTTP通信において、クライアントからWebサーバーの送られるのが
HTTPリクエスト。

HTTPリクエストの構成（中身）

HTTPリクエストは

• HTTPリクエスト行（リクエストライン）
• HTTPリクエストヘッダ（ヘッダ）
• HTTPリクエストメッセージボティ（メッセージボディ）

で構成される。

構造としては

• HTTPリクエスト行
• HTTPリクエストヘッダ
• 空行
• HTTPリクエストメッセージボティ

のように、ヘッダとボディの間に空行が入る。

HTTPリクエスト行（リクエストライン）

言い方がリクエスト行だったりリクエストラインだったりする。
書式は

【メソッド】[空白]【URI】[空白]【HTTPのバージョン】

なる。

メソッドにはHTTPメソッド（GETとかPOSTとか）が入り、
URIにはアクセスするリソースが入る。

HTTPリクエストヘッダ（ヘッダ）

ヘッダーにはリクエストの詳細情報(User-Agent当)が入る。

書式は

【フィールド名】:【内容】

の形になってる。

HTTPリクエストメッセージボティ（メッセージボディ）

メッセージボディには画面の入力内容など、サーバー側に渡したい情報が入る。
GETのように必要がない場合は特に何も書かれない。

パスパラメータとは？

リソースを識別するために必要な情報が指定される
URIのホスト名（ドメインでない）かつ、クエリパラメータでない部分のこと

https://scrawledtechblog.com/blog?flg=true&id=3

であれば「blog」がパスパラメータ。

クエリパラメータとは？

リソースを操作して取得するのに必要な情報が指定される
?の後に指定されているもの

ルールとしては

• URLの?以降の文字列
• 「名前=値」の形式
• 複数ある場合は「&」でつなげる

例えば

https://scrawledtechblog.com/blog?flg=true&id=3

であれば「flg=true&id=3」がクエリパラメータ。

クエリパラメータ、クエリ文字列、クエストリング、URLパラメータなど
呼び方がたくさんある。

HTTPレスポンスとは？

HTTP通信において、Webサーバーからクライアントへ返されるのが
HTTPレスポンス。

HTTPレスポンスの構成（中身）

HTTPリクエストは

• HTTPステータスライン（ステータスライン）
• HTTPレスポンスヘッダ（ヘッダ）
• HTTPレスポンスボティ（レスポンスボディ）

で構成される。

構造としては

• HTTPステータス行
• HTTPレスポンスヘッダ
• 空行
• HTTPレスポンスボティ

のように、HTTPリクエストど同様にヘッダとボディの間に空行が入る。

HTTPステータス行（ステータスライン）

ステータスラインにHTTPリクエスト結果が書いてある。
重要なのはステータスコードで「200」とか[404]とか

書式は

【HTTPのバージョン】[空白]【ステータスコード】[空白]【ステータスコードの説明】

なる。

※ステータスコードはググればすぐでてくるので割愛。

HTTPレスポンスヘッダ（ヘッダ）

ヘッダーにはレスポンスの詳細情報（サーバー情報とかコンテントタイプ）が入る。

書式は

【フィールド名】:【内容】

の形になってる。

HTTPレスポンスボディ

HTTPレスポンスにはリクエストで要求された相手がほしかった情報が入っている
例えば

• webページの表示要求であればHTMLが返される
• REST APIに対する要求であれば処理結果としてJSON形式のデータが返される

のような感じ。

まとめ

今まで何となくイメージでHTTPを使ってきたが、REST APIを設計するにあたり
HTTP周りの用語や構造を調べて整理してみた。

参考

• REST API （RESTful API）
• 0からREST APIについて調べてみた
• Kongの使い方を知る①
• URIとは？「URL」と「URI」の違いを解説！
• 最近話題の API や REST API ってなに? ～応用編～
• 「HTTPリクエスト」と「HTTPレスポンス」
• [RESTful API]パスパラメータ、クエリパラメータ、リクエストボディの違いと設計
• HTTPリクエストライン