AWSインフラエンジニアを肩書としている私ですが、
最近のプロジェクトではサーバレスアーキテクチャを採用したシステムの
バックエンド設計を担当しています。（コーディング経験ほぼ無いのに…笑）
そんな中初めて経験した業務の一つが「API設計」です。
APIがどんなものかは何となく分かっているつもりでも、いざ設計するとなると分からないことだらけ…
過去プロジェクト資料やGoogle先生を頼りに試行錯誤した結果どうにかできるようになったのですが、
その過程で気づいたポイントや観点を（ものすごく）簡単にまとめたいと思います。
APIをHTTPで呼び出すとき、Requestという通信が行われます。
呼び出し元であるクライアントからバックエンドに情報を渡してあげたいとき、
このRequestに情報を乗せて送ります。
Requestで情報を乗せる場所は、具体的にいうと
の２種類があります。APIを呼び出すときのURLにParameterとして渡す方法もありますが、
この辺の使い分けは渡したいデータの
「量」「構造（親子関係）」「秘匿性（セキュリティ）」
の有無などで変わってきます。
Requestを受けたバックエンドは、色々な処理をした後に結果をResponseという通信で返します。
クライアントは受け取ったResponseから結果を取り出し、次の処理で利用します。
ResponseにもHeaderとBodyがありますが、だいたいBodyに結果を入れることがほとんどだと思います。
API呼び出しを受けてバックエンドが処理をした結果が、どんなときでも成功するとは限りません。
失敗してしまった場合はその理由を添えてクライアントに知らせる必要があります。
その場合、Responseに対してエラーコードを付与することで
失敗した理由を簡潔に伝えることができます。（実は成功している場合でもコードを返しているのですが）
このコードのことを「HTTPステータスコード」と言ったりしますが、
詳しいことは↓のリンクが分かりやすいので読んでみてください。
https://qiita.com/NagaokaKenichi/items/eb85b5fbb719d60c6627
もっと詳しく話そうと思うと色々あるのですが、今回はこの辺で切り上げておきます。
気が向いたら別の記事で書きますね。
入会申込
ログイン
