Webエンジニアの技術ブログ

日々学んだことをアウトプットしていくためのブログです。

Web API設計の要点まとめ

全体的な

  1. APIは開発のUIのため利用者がわかりやすい設計にする

リクエスト(URL)

  1. HTTPメソッドで操作
  2. URLのエンドポイントは名詞で命名
  3. 単数系ではなく複数形で
  4. スネークケースではなく、ケバブケースで
  5. バージョンはURLに含める
  6. 条件(ソートなど)の指定は、リクエストパラメータで
  7. 関連データの場合親のリソースがわかるURLに(例: posts/:id/comments)

レスポンス

データの内部構造について

  1. 基本的にはXMLではなく、JSONを使用する
  2. APIのアクセスがなるべく少なくできるようなレスポンスデータ
  3. 必要のないプロパティは返さない(サイズを小さくするため)
  4. アクセス回数を少なくするためだからといって一度に大量のデータを返さない(その塩梅はAPIユースケースを考えてよしなに)
  5. 無駄にラップ(ネスト・入れ子)しすぎない(サイズ小さくするため)
  6. 大きい整数は文字列として返す(サイズ小さくするため)

命名について

  1. プロパティ名はキャメルケースで
  2. 扱うデータによって複数形or単数系の命名をする
  3. 完結でわかりやすい単語を用いる

エラー

  1. 適切なステータスコードを返す
  2. エラーの原因がわかるエラーメッセージ

セキュリティー

  1. SSL通信を行う(https)
  2. トークン認証を使う
  3. トークン認証はURLではなくヘッダに持たせる
  4. エラーメッセージに重要な情報(個人情報など)を載せない

参考資料

翻訳: WebAPI 設計のベストプラクティス - Qiita

API設計スキルを次のレベルに引き上げるベストプラクティス22選 - Qiita

Web API 設計入門

Kubernetes入門

目的

Kubernetesとは

kubenetes(クーベネティス・クバネティス)とは、コンテナのオーケストレーションツールである。
オーケストレーションとは、システム全体の統括をし複数のコンテナ(=サーバー)を管理することができるもの。
そのため、複数のサーバーが存在し、それぞれのサーバーの中で更に複数のコンテナが存在するのが前提と言える。
コンテナを作成するのみのdocker composeとは異なり、kubernetesコンテナの作成・監視・維持を行うため、常に望ましい状態に保つことができるツールである。 またkubenetesは、よくk8sと略される。

構成と用語

マスタノード

マスタノードは、コンテナを動かすのではなく、コンテナ(=ワーカノード)を管理する役割を担っている。コントロールプレーン(制御盤)というものでワーカノードを管理している。

マスターノード(=コントロールプレーン)は以下のような構成になっている。
kube-apiserver
外部とやり取りをするためのコンポーネントで、kubectlコマンドからの命令を受け取って実行する。

etcd
クラスター情報を管理するキーバリュー型のデータベース(noSQL)。

kube-scheduler
Podをワーカノードに割り当てたり、状態を監視する役割のコンポーネント。割り当てがない場合は、そのワーカノードにPodを割り当てる。

kube-controller-manager
controllerの統括・管理を行うコンポーネント

cloud-controller-manager
クラウドサービスと連携を行う。

ワーカーノード

ワーカーノードは、実際にコンテナを動かす役割を担っていて、マスタノードによって管理されている。
管理者の方で設定などをいじるのはマスタノードであるため、直接ワーカノードを操作することはない。

ワーカノードの構成
kubelet
マスタノードのkube-shedulerと連携していて、ワーカノード上にPodの設置を行う。またPodの状況をkube-shcedulerに通知することも行っている。

kube-proxy
ネットワーク通信のルーティングをする仕組み。

クラスタ

マスタノードとワーカノードで構成されたk8sの一群をのことをクラスターと言う。
マスタノードに設定された内容によってワーカノードが自律的に動くためクラスターは自律的に動くと言える。

クラスターの構成図(参照)

Pod

k8sでは、コンテナはPodという単位で管理されていて、コンテナとボリュームがセットになったものになる。
基本的には、1Pod 1コンテナだが、複数のコンテナにすることも可能で、コンテナごとが連携したプログラムの場合などに複数のコンテナを1Pod内で管理することもある。

Service(サービス)

Podをまとめて(束ねる)管理するもので、単一のサービスが管理するPodは、基本的に同一のPodになる。異なる構成のPodは違うサービスが管理する。
また、サービスで管理するPodは、マスタノードを跨ぐケースの存在する。

さらに、ロードバランサー(負荷分散装置)の役割を担っている。サービスには自動的に固有のIPアドレス(Cluster IP)が割り振られており、本物のロードバランサー(もしくはIngress)はそのIPアドレスに対してアクセスを行い、アクセスされたサービスは複数のPodに対して適切に割り振る。

上記の内容とまとめて図解すると、以下のような感じ。

レプリカセット(レプリカ)

Podの数を管理するもの。そのためPodはレプリカセットとアクセスを管理するサービスの2つによって管理されている。またレプリカセットにより管理されている同一構成のPodをレプリカ(複製品)という。
レプリカセットは、単独で使用することはなく、後述するデプロイメントとセットで使用する。

デプロイメント

Podのデプロイを管理するもので、Podがどのイメージを使用するかなどのPodに関する情報を持っている。

リソース

前述したPodやサービス・デプロイメントなどのことをまとめて、リソースという。リソースは、他にもさまざまなものがあるが(cronjobなど)基本的なリソースは上記で説明したものになる。

参考資料

Kubernetesのコンポーネント | Kubernetes / Kubernetes Documentation | Kubernetes

Docker入門 仕組みについて

Docker とは?

ざっくり一言で言うと、「データやプログラムを隔離」できるようにした仕組みになる。

「コンテナ技術」などよく言われるが、結局Dockerを利用する目的は「データ・プログラムの隔離」であり、その手段としてコンテナという技術を使用している。

実際にデータやプログラムを隔離する場所がコンテナである。
コンテナを操作する場合は、Docker Engineをインストールする必要があり、コンテナを作成するにはイメージというものから作成する。

データやプログラムを隔離することができるため、それぞれの実行環境に依存せず開発を行うことができるという利点がある。

動く仕組みについて

Dockerを動かすには、まず物理的マシン(PC)の中にLinux OS,Docker Engineが必要になりその上でコンテナがある。
そしてコンテナを操作するため、コンテナ内にはLinux OSの周辺部分が必ず用意されており、それを通じて操作できるようになっている(作成した時は空っぽではないということ)

Linux OSの周辺部分
少しOSの話にはなるが、OSはソフトウェアなどプログラムの命令をハードウェアに伝える役割を担っている。
周辺の部分とカーネルで構成されており、周辺部分がプログラムの指令を受け取りカーネルに伝え、カーネルがハードウェアを操作している。

先ほど説明したようにコンテナの中にLinux OSの周辺部分が備え付けてあるため、そこを通じてカーネルにプログラムを伝達しているため、コンテナを操作できるようになっている。

このようにDockerはLinux OSで動くため、WindowsMacでDockerを動かすには、何らかの方法でLinux OSを導入しなければいけない。
方法としては基本的に2種類で、仮想環境を立ち上げLinux OSをインストールしてその中で操作するか、Docker Desktop for Mac or Docker Desktop for Windows をインストールしてLinux環境を用意する必要がある。

イメージとコンテナ

コンテナを作成するときは、イメージを基に作成する。イメージはコンテナの素となるもので、「設計図」のようなものである。
イメージからコンテナを作成できるのはもちろんのこと、逆にコンテナからイメージを作成することもできるため、手を加えたコンテナがあった場合それを素にイメージを作成する。ということもできる。

イメージは1から自作することもできるしDocker Hub(イメージを誰でも登録・公開・利用できるサイト)で既に作成されているイメージを利用することもできる
また、Docker Hubで提供されているイメージをカスタマイズして使用することもできる。

コンテナのライフサイクルについて

Dockerのコンテナは、1つのコンテナをアップデートしていって「長く使用する」のではなく、「作っては捨てる」という使い方をする。
コンテナは基本的に複数のコンテナを同時稼働することを想定しているため、1つのコンテナをアップデートしていると非常に効率が悪い。そのため、古いコンテナは捨て新たにイメージからコンテナを作ってしまい、乗り換えることで効率的にコンテナを利用することができる。
コンテナのライフサイクル・・・作成→起動→停止→廃棄→作成…

データ保存について

前述したようにコンテナはすぐに作成されるため、データはDockerをインストールしている物理的マシンのディスクにマウントし、そこに保存する。
そのためコンテナを削除してもマシン上にデータが保存されているため、削除されることなくコンテナを利用することができる。