【入門】Web APIでの基礎知識

12172 ワード
Web api api テキストリンク

勉強用と忘れないようにメモ

１．Web APIをなぜ学ぶのか

  • マイクロサービスの流行
  • 便利なSaaSが増え、API開発が主流のため
  • フロントエンドの役割が広がった（フロントエンドでも実装する機会がある）、jaｍ（JAVASCRIPT、API、マークダウン）での開発が多いため

２．webの用途

  • webサイト　情報の閲覧をする（企業のコーポレートサイト）
  • webアプリケーション　投稿、検索、編集機能など機能が搭載されているユーザーとの対話型のこと（ツイッターやYOUTUBE）
  • ユーザーインターフェースとしてのweb 商品などの説明書や設定画面
  • web API　プログラムが使うためのweb（データの送受信や編集などをプログラムを使って通信する）

３．webを支える技術

  • HTTP ：通信のためのルール（プロトコル）
  • URI ：リソースを識別するID　（URIの中にURLが含まれているイメージ）
  • HTML　：webで表示するための文書フォーマット

４.集中システムと分散システム

  • 集中システム　メインフレームのこと　１つのでっかいサーバーに対して処理を一挙におこないシステムを動かすこと　１９８０年まで主流だった
  • 分散システム　Webのこと　複数のコンピュータが相互に処理をして１つのシステムを作っていくこと

５.RESTとは

RESTとはアーキテクチャスタイル（設計、思想、作法）のこと
アーキテクチャスタイルは　REST
アーキテクチャは　 サーバー、ブラウザ、etc
実装は　 Apache、Chrome、etc なイメージ

リソースもRESTの一部。
webにおけるリソースとはweb上に存在する名前を持ったあらゆる情報（URIもリソースの一部）

RESTを構成する６つのアーキテクチャスタイル（ルールみたいなもの）
1.クライアント・サーバー　:UIと処理を分離する
2.ステートレスサーバー　:クライアント状態をサーバーが管理しない
3.キャッシュ :サーバーから取得したリソースの再利用。クライアントにキャッシュ情報は保存されている。情報の鮮度は失われる
4.統一インターフェース　:操作可能なインターフェースを制限（get,put,deleteとメソッドを制限）
5.階層化システム　:システムを階層に分離
6.コードオンデマンド　: クライアントでDL&実行（JAVASCRIPTのように必要なときにダウンロードして実行すること）

通信の流れ
クライアント　⇔　プロキシサーバー　⇔　ステートレスサーバー　
クライアント（プログラムをDL）　⇔　ステートレスサーバー　⇔　DB　

６.URI

  • URIスキーム :通信プロトコルを指す（http or httpsがほとんど）
  • ユーザー情報　:＜username＞:＜password＞形式
  • ホスト名 :DNSで名前解決できるドメイン名　or IP　アドレス
  • ポート番号　:プロトコルで用いるTCPポート番号
  • パス　:階層を表す、一意なリソース
  • クエリパラメータ :？の後がクエリパラメータ。名前=値形式の追加情報
  • URIフラグメント　：Webページ内部の位置を指す

URIパスの指定方法

  • 絶対URI　：先頭からのフルパス
  • 相対URI　：起点からの相対的なパス
  • ベースURI　：相対URIの起点を決めるためのURI

URIと文字
URIではASCII文字が使える
日本語などの文字をURIで使うには％エンコーディングが必要

７.クールなURIの設計方法

クールなURIとは変わらない、普遍的なURIのこと
URIはリソースであり、リソースが変わらないということはアクセスが永続的にできるということなので、クールだねとのこと

  • プログラミング言語に依存した情報を含めない　ファイル拡張子、開発用ディレクトリ、大文字、、etc
  • メソッド名やセッションIDを含めない
  • URIにはリソースを指し示す名詞を使う　動詞はHTTPメソッドで使うので使わない
  • なるべくシンプルかつ人間が読んで理解できる

URIの変更方法
301 Redirectを使ってURIの変更を知らせるとページランクを引き継げる（SEO的に○）

301 Redirect　：恒常的なURIの変更
302 Redirect　：一時的なURIの変更

URIの設計テクニック

URIの不透明性を保つためにクライアント側でURIを構築しない

  • URIからリソースの構造を推測できないようにする
  • URIに拡張子を含めるとその言語で操作されるため避ける
  • API経由以外でサーバーから情報を抜き出される

８.HTTP　TCP/IPの４階層モデル

HTTPはTCP/IPというネットワークプロトコルがベースになっており、以下の層のようになっている

HTTP　アプリケーション層　アプリケーション毎の通信プロトコルを決定する層　：WEBページであればhttpプロトコル、メールの送信であればSMTPプロトコル

TCP　トランスポート層　データ転送の抜け漏れをチェックする層

IP　インターネット層　データを送るための層　：IPアドレス、パケット（データを小分けにしたもの）などの技術が関連

Ethernet　ネットワーク・インターフェース層　：LANケーブルなどの物理的な層

HTTPのバージョン
HTTP０．９　：GETメソッドのみ
HTTP１．０　：レスポンスの追加（ステータスコードなど）、POSTメソッドの追加
HTTP１．１　：原則、１通信＝　１リクエスト　＝１レスポンス
HTTP２．０ ：ストリームの多重化による複数リクエストの同時通信

９.リクエストとレスポンスの流れ

１，【クライアント】リクエストMSGの構築　【サーバー】待機
２，【クライアント】リクエストMSGの送信　【サーバー】リクエストMSGの受信
３，【クライアント】待機　　　　　　　　【サーバー】リクエストMSGの解析
４，【クライアント】レスポンスMSGの受信　【サーバー】HTML取得
５，【クライアント】レスポンスMSGの解析　【サーバー】レスポンスMSGの受信
６，【クライアント】レンダリング処理　【サーバー】レスポンスMSGの送信

HTTP１．１とHTTP２．０の違い
上記のリクエストとレスポンスの処理を複数同時におこなえるのがHTTP２．０

１０.HTTPメッセージ

リクエスト レスポンス
リクエストライン メソッド：GET
パス：/posts/123
プロトコルバージョン：HTTP/2		 プロトコルバージョン：HTTP/2
ステータスコード：200
テキストフレーズ：OK
ヘッダー（メタデータ） 　　　 accept:要求するデータ形式
Host：リクエスト先のホスト名
User-Agent：リクエスト元情報		 content-type：帰ってくるデータ形式
ボディ（表データ） POSTやPUTのときに使う作成したいリソース情報 サーバーが返す実際のデータ　HTMLやJSONなど

参考　APIを叩けるサイト httpsbin

HTTPはステートレス通信で行うのが良いとされている
ステートレスはクライアントの情報をサーバーが管理しない
ステートフルはクライアントの情報をサーバーが管理する　
違いがある

  • サーバーがクライアントの状態を管理せずに通信する
  • ステートフルは簡潔　接続先が多くなると管理しきれない（）
  • ステートレスは冗長でデータ量が多いがシンプル
  • ステートレスで通信エラーが起きると重複する可能性あり

１１.HTTPメソッド

メソッド CRUD 役割
GET Read リソースの役割
POST Create 子リソースの作成、リソースへのデータ追加,etc
PUT Create/Update リソースの更新（存在しなければ作成）
DELETE Delete リソースの削除
HEAD ー リソースのヘッダ取得
OPTION ー リソースがサポートしているメソッドの取得

HEAD、OPTION以外の４つのメソッドでCRUDを実装することが多い

１２．べき等性と安全性

べき等性：ある操作を何回行っても結果が同じこと
安全性：捜査対象のリソースの状態を変化させないこと

メソッド べき等性 安全性
GET ○ ○
POST ✕ ✕
PUT ○ ✕
DELETE ○ ✕
HEAD ○ ○
OPTION ○ ○

１3．ステータスコードの大分類

ステータスコード　：レスポンスの意味を示すコード

ステータスコード 意味 詳細
1xx 処理中 処理が継続していることを示す
クライアントがそのままリクエストを継続するか再送信するかなど判定
2xx 成功 リクエストの成功を示す
3xx リダイレクト 他のリソースへのリダイレクトを示す
Locationヘッダーを見て新しいリソースへ接続する
4xx クライアントエラー クライアントのリクエストが原因でエラーが発生したことを示す
5xx サーバーエラー サーバー側で何らかのエラーが発生したことを示す

*先頭の数字でどのようなレスポンスか把握できる
*未知のステータスコードは先頭の数字で判断

よく使うステータスコード

ステータスコード テキストフレーズ 意味
200 OK GET：取得したリソースがメッセージ本文で送信される
HEAD：ヘッダー情報がメッセージ本文で送信される
PUT or POST：操作の対象がメッセージ本文で送信される
201 Created 新たなリソースが作成された、PUTまたはPOSTのレスポンス
204 No Content リクエストのレスポンスとして送信するコンテンツはないがリクエストは成功
301 Moved Permanently リソースの恒久的な移動
400 Bad Request クライアントエラー。リクエストの構文やパラメータが間違っている
403 Forbidden 認証されてないなどコンテンツのアクセス権がない（ログイン認証が必要なページにアクセスしたりで発生する）
404 Not Found リソースが存在しない、URLを解釈できなかったなど
500 Internal Sever Error サーバー側で処理できないエラーが発生。相手側に問題がある事が多い。
502 Bad Gateway ゲートウェイとなるサーバーが正常に作動しなかった
503 Service Unavalliable サーバーがメンテナンスや過負荷などでダウンしている

参考　HTTPステータスコード｜MDN

ステータスコードによるエラー処理

  • Accceptヘッダに応じたフォーマットでエラーを返す
    type/html：HTMLでエラーを返すページを作成して返す
    application/json :JSONでresponse.error.messageなどを表示する
  • SPAのバックエンドとしてJSON形式のAPIを利用しているときはステータスコードに応じでコンポーネントを作成する場合もある↓
app.js
const fetchData = async () => {
 const res = await fetch('http://localhost:3000/URI')
 if (res.status === 400){
 //クライアントのエラー処理
 }
}

１4．リクエストの付加情報を表すHTTPヘッダについて

MINEメディアタイプの指定

  • MINEはMultipurpose Internet Mail Extensions
  • Content-Typeヘッダでメディアタイプを指定（type／subtype形式）
  • charsetパラメータは文字エンコーディングを指定 Content-Type：　application /json; charset=utf-8
主要なType 意味 Type/subtype例
text 人が読んで理解できる text/plain
image 画像データ image/jpeg
audio 音声データ audio/mpeg
video 動画データ video/mp4
Application その他データ application/json

様々なヘッダ情報

ヘッダ個別 例 意味
言語タグ Conttent-Language.ja-jp リソースを表現する言語
コンテントネゴシエーション Accept text/html,application/xml クライアントが処理可能なメディアタイプ
ボディの長さ content-length:47 レスポンスボディのサイズ
チャンク転送 Transfer-Encoding:chunked 大きなデータをチャンク（分けて転送する）

HTTP認証のためのヘッダ

  • リソースのアクセスに制限がかかっている場合認証が必要
  • Authorizatiounヘッダに認証情報を付与する Authorizatioun：　Basic　asdughawudfahjh== (asdughawudfahjh==はbase64エンコードで人には読めないが簡単にデコードできる)
認証方法 仕様 特徴
Basic認証 base64でエンコードされたユーザーIDとパスワードを使用 簡単にデコードできる。HTTPSによる通信暗号化が必須
Digest認証 デコードできないハッシュ化されらパスワードを使用 メッセージは暗号化されないので通信暗号化が必須
Bearer認証 権限付きのトークンを取得して使用する OAuthで保護されたリソースなどの認証に使う

１4．キャッシュ

  • リソースを再利用できる仕組み
  • 現在の使用ではCache-Controlヘッダを使うことがほとんど
  • 検証と再取得の条件を設定する
指定方法 目的
Cache-Control：no-store キャッシュしない
Cache-Control：no-cache キャッシュするが再検証する
Cache-Control：max-age=86400 相対的な有効期限を設定。単位は秒（86400秒=24時間）
Cache-Control：must-revalidate 必ず検証する