Skip to content

Latest commit

 

History

History
886 lines (522 loc) · 51.9 KB

README-ja.md

File metadata and controls

886 lines (522 loc) · 51.9 KB

中文版 | ENGLISH | 한국어 | РУССКИЙ | Português | Persian/فارسی

プロジェクトガイドラインPRs Welcome

開発中の新たなプロジェクトは草原のようですが、メンテナンスは誰にとっても悪夢になります。 ここには私たちが見つけ記載し、集め考えたガイドラインがあります。 このガイドラインはほとんどのelsewhenの JavaScript のプロジェクトで機能しています。 もしもベストプラクティスを我々と共有したかったり、このガイドラインの項目は削除した方が良いと思ったら気軽に私たちに報告してください。

1. Git

Git

1.1 Git のルール

いくつかの Git のルールを覚えておきましょう。

  • feature ブランチで作業しましょう。

    Why:

    全作業がメインブランチではなくて独立した作業専用のブランチで完結するからです。そうすることによって混乱をきたすことなく複数のプルリクエストを作成することができます。作業途中のコードや不安定なコードを master ブランチを気にすることなく繰り返し作れます。もっと読む...

  • developブランチからブランチを切りましょう

    Why:

    こうすることで master のコードを問題なくビルドできることができ、master はリリース用にほとんどそのまま利用できます。(プロジェクトによってはやりすぎかもしれません。)

  • developとmasterブランチに直接 Push するのはやめましょう。プルリクエストを作成しましょう。

    Why:

    developとmasterブランチが更新されるということはチームメンバーにその機能を実装し終わったと伝えることと同義です。直接 Push さえしなければ、コードレビューや新たな機能の議論がしやすくなります。

  • feature ブランチを Push してプルリクエストを作成する前にローカルのdevelop ブランチを最新にして、feature ブランチをインタラクティブリベースしましょう。

    Why:

    リベースはブランチ（masterかdevelopか）をマージします。また local に作ったコミットをマージコミットを作成せずに Git のヒストリーのトップに並べ替えます。コンフリクトがなければ。そうすることで綺麗で素晴らしいヒストリーが残ります。もっと読む...

  • リベースする間やプルリクエストを作る前にコンフリクトを解消しましょう。

  • マージした後のブランチは local、remote 共に削除しましょう。

    Why:

    不要になったブランチをが含まれることで自身 local のブランチのリストが乱雑になるでしょう。またマージする時にのみ一回だけブランチ（masterかdevelop）に戻ることを保証します。feature ブランチは作業中だけ存在すべきです。

  • プルリクエストを前に、feature ブランチのビルドの成功を確認して全てのテストを通しましょう。(コードのスタイルも含めて確認しましょう。)

    Why:

    安定的なコードを追加しようとする時、もし feature ブランチのテストが失敗したとすると、最終的なマージ後のテストも失敗する可能性が高いです。加えてプルリクエストを作成する前に、スタイルチェックを行う必要があります。スタイルチェックを行うことで可読性が上がり、実際のコードと一緒にフォーマットによる修正を減らすことに繋がります。

  • こちらの.gitignoreファイルを使いましょう。

    Why:

    この.gitignore ファイルには remote のリポジトリに含めたくないシステムファイルのリストを列挙しています。またユーザーが多くの人が使うエディタ用のフォルダやファイル(依存フォルダも同じように)も含めてます。

  • developとmasterブランチを保護しましょう。

    Why:

    プロダクションに備えているブランチに予期しない破壊的なコミットが Push されることを防ぎます。

1.2 Git workflow

上記の理由のために、私達はFeature-branch-workflowとInteractive Rebasing、Gitflow の要素のいくつか(名前付と develop ブランチを持つこと)を使います。主なステップは以下の通りです。

  • 新しいプロジェクトにとっては初期の git の設定。features/changes ブランチの作成は の次のステップなので無視しましょう。

    cd <project directory>
git init

  • feature/bug-fix ブランチを作成する。

    git checkout -b <branchname>

  • コードを変更する。

    git add
git commit -a

    Why:

    git commit -aを使うと本文から主題を切り離して始めることができます。詳しくはsection 1.3を読みましょう。

  • 取り込まれていない変更を取得する為にリモートのリボジトリと同期しましょう。

    git checkout develop
git pull

    Why:

    こうすることでコンフリクトを含めながらプルリクエストを作成するのではなくてリベース(のちに)しつつ、コンフリクトに対処できる可能性が高まります。

  • feature ブランチにインタラクティブリベースをすることで常に develop の変更を取り込みましょう。

    git checkout <branchname>
git rebase -i --autosquash develop

    Why:

    --autosquash は全てのコミットを一つにまとめることができます。一つの feature に対して複数のコミットがある状態は望ましくありません。もっと読む...

  • もしコンフリクトしてなかったらこの章は飛ばして大丈夫です。ただしもしコンフリクトが起きてたら解決しましょう。そしてリベースを続けましょう。

    git add <file1> <file2> ...
git rebase --continue

  • 自分のブランチを Push しましょう。リベースはヒストリーを改変しますので、リモートに Push する際は-f のオプションをつけて Push する必要があります。もし他の人が同じブランチで作業をしていたらより破壊的でない--force-with-leaseを使いましょう。

    git push -f

    Why:

    リベースをすると、作業ブランチのコミットヒストリーを変えることになります。結果として Git に普通のgit pushは拒否されるので代わりに -f や--force フラグを使えば大丈夫です。もっと読む...

  • プルリクエストを作りましょう。

  • プルリクエストが受け入れられたら、レビュワーによってマージされて課題が閉じられます。

  • マージが完了したらローカルのブランチを消しましょう。

    git branch -d <branchname>

    必要のないリモートブランチを全て削除するコマンド。

    git fetch -p && for branch in `git branch -vv | grep ': gone]' | awk '{print $1}'`; do git branch -D $branch; done

1.3 良いコミットメッセージの書き方

コミットを作成して維持するための良い指針を持つと、Git をうまく使うことができ他の開発者との共同作業をとても簡単にします。ここにいくつかの経験則があります。(ソース)

  • 本文を改行することで主題と切り離しましょう。

    Why:

    Git は最初の行をそのコミットのサマリとして区別します。実際git logの代わりにgit shortlogを使うと、コミット ID とサマリーのみで構成される長いコミットメッセージのリストを見ることができます。

  • 主題は 50 文字以内、本文を含めても 72 文字以内に制限しましょう。

    why

    コミットはできる限りきめ細やかで完結あるべきで、コミットメッセージを冗長にすることは避けましょう。詳しく読む

  • 主題の先頭は大文字にしましょう。

  • ピリオドで終わるのをやめましょう。

  • 主題部分では命令法 を使いましょう。

    Why:

    コミッタが何を行ったかわかりやすいメッセージを書きましょう。コミットがマージされた後にそのコミットが何をしたのかをうまく説明できるように考えるといいでしょう。もっと読む...

  • 本文は How ではなくて What と Whyを説明しましょう。

2. ドキュメント

ドキュメント

  • こちらのテンプレートを使ってREADME.mdを作成しましょう。空白のセクションがあっても気にしなくても大丈夫です。
  • 一つ以上の Git リポジトリがあるようなプロジェクトでは、各々のREADME.mdファイルをリンクさせてあげましょう。
  • プロジェクトの成長に合わせてREADME.mdの情報を最新に保ちましょう。
  • コードにはコメントを書きましょう。その際には自分の意図をできる限り簡潔に書くように心がけましょう。
  • もしコードや試みているアプローチについて github や stackoverllow でオープンな議論があれば、そのリンクもコメントに含めましょう。
  • ダメなコードに対する言い訳を書くのはやめましょう。コードを綺麗に保ちましょう。
  • 綺麗なコードを全くコメントがないことに対する言い訳にするのはやめましょう。
  • コードの成長に合わせてコメントを最新に保ちましょう。

3. 開発環境

開発環境

  • 必要ならdevelopment, test とproductionの環境を分けて定義しましょう。

    Why:

    データやトークンや API、ポートなど環境によって必要とされるものは様々です。。。テストの自動化と手動のテストを簡単にさせるために、developmentモードは予測可能なデータを返すフェイクの API が欲しいかもしれません。もしくは Google Analytics はproductionでだけ有効にしたかったり様々でしょう。もっと読む...

  • 環境別の Config ファイルを環境毎に適用するようにして、コードベースに定数として決して書き込まないでください。サンプル

    Why:

    トークン、パスワードなど様々な重要な個人情報を持っています。 その情報はコードベースがいつ公開されてもいいように、コードベースとは切り離さないといけません。

    How:

    .envファイルを情報を保持するために使いましょう。そのファイルは.gitignoreに加えて、Git リポジトリからは除外されるようにします。その代わりに.env.exampleのようなサンプルを他の開発者向けのガイドとしてコミットしておきましょう。production 環境用に、環境設定は標準的なやり方で設定するようにしましょう。 もっと読む...

  • アプリケーションを開始する前に環境変数を validate することをオススメします。サンプルを参照 変数を Validate するためにjoiを使っています。

    Why:

    トラブルシューティングに費やす時間を節約することに繋がります。

3.1 統一された開発環境

  • node のバージョンをpackage.jsonの中のenginesに設定しましょう。

    Why:

    どのバージョンの node をそのプロジェクトで使うべきかを示すことができます。もっと読む...

  • さらにnvm を使って.nvmrcをプロジェクトルートに作成しましょう。ドキュメント内に記述を残すことを忘れないようにしましょう。

    Why:

    nvmを使う人は誰でも誰でもnvm useを使うことで node のバージョンを切り替えることができます。もっと読む...

  • preinstallスクリプトを使って node と npm のバージョンを確かめるのがいいでしょう。

    Why:

    npm の新たなバージョンでインストールすると依存関係のライブラリが失敗することがあります。

  • できるならば Docker イメージを使いましょう。

    Why:

    Docker イメージは全てのワークフローを跨いで同じ環境を提供してくれます。依存関係やコンフィグファイルに悩む必要があまりないようになります。もっと読む...

  • グローバルのモジュールを使うのではなくローカルのモジュールを使いましょう。

    Why:

    同僚が特定のモジュールを彼らのマシンにすでにインストールしていることを期待するのではなく、使うライブラリは共有できるようにしておきましょう。

3.2 一貫した依存関係

  • チームメンバーが同じ依存関係を取得できることを確認しましょう。

    Why:    > コードにはどんな開発マシンでも同じ挙動をしてほしいからです。もっと読む...

    how:

    npm@5以上でpackage-lock.jsonを使いましょう。

    npm@5 は使ってない:

    Yarnを使いREADME.mdを確かめることで代替手段とすることができます。各ライブラリをアップデートした後にロックファイルとpackage.json は同じバージョンを保持しているでしょう。

    Yarnという名前が気にくわない:

    それは残念です。 古いバージョンのnpm用に、パブリッシュする前に新しいライブラリをインストールしたりnpm-shrinkwrap.jsonを作るときには、—save --save-exactを使いましょう。もっと読む...

4. 依存関係

Github

  • 使用可能な最新のパッケージを保ちましょう。 e.g.,npm ls --depth=0. もっと読む...

  • 無関係であったり使っていないパッケージを確認しましょう: depcheck. もっと読む...

    Why:

    もしかしたら使っていないライブラリが production のサイズを増加させているかもしれません。使っていない依存関係を見つけてそれを消すようにしましょう。

  • ライブラリをインストールする前に、そのライブラリがコミュニティでよく使われているかどうかを確認しましょう。npm-stat。もっと読む...

    Why:

    多く使われているということは多くのコントリビューターがいるということで、それは良いメンテナンスが行われているということになります。そのことはバグが開発者によっていち早く発見され、修正されることに繋がります

  • ライブラリをインストールする前に、それがいい機能を持っているか、多くのメンテナーがいて成熟したバージョンを頻繁にリリースしているライブラリかを確認しましょう。: e.g., npm view async. もっと読む...

    Why:

    もしメンテナーが修正をマージしなかったりパッチを素早く当てないと、コントリビュータが効率的な開発を行えなくなるでしょう。

  • それほど知られてないライブラリが必要な場合には、使用する前にチームメンバーと議論しましょう。

  • ライブラリはビルドを破壊しない限りは常に最新で動くかを確かめましょう: npm outdated もっと読む...

    Why:

    依存パッケージの更新はたまに破壊的変更が含まれていることがあります。アップデートが出たときには常にリリースノートを確認しましょう。何かあったときにトラブルシューティングを簡単にするために、依存ライブラリを一つ一つ更新しましょう。npm-check-updatesのように素晴らしいツールを使いましょう。

  • 依存パッケージに公開されている脆弱性が含まれている場合があるのでチェックしましょう。 e.g.,Snyk

5. テスト

テスト

  • 必要であればtestの環境を用意しましょう。

    Why:

    通常は end to end のテストをproductionに行うだけで十分なですが、例外がいくつかあります。統計データをproduction環境で有効にしたくなく、テストデータでダッシュボードを汚したくない場合です。あとはproductionの API に制限があって、テストをする際のリクエスト数が制限に達してブロックされてしまう場合です。

  • 単体テストコードはテストされるファイルの隣におきましょう。 moduleName.spec.jsのように*.test.js や *.spec.js のようなファイル名が慣例となっています。

    Why:

    ユニットテストを探すためにフォルダ構造を掘り進めたくないでしょう。もっと読む...

  • 追加のテストファイルがどこにあるか混乱を避けるために隔離されたフォルダに入れましょう

    Why:

    いくつかのテストコードは実装コードと関連してないことがあります。他の開発者が見つけやすいフォルダ(__test__フォルダのような)にテストコードをおきましょう。__test__フォルダはスタンダートであり、様々な JavaScript フレームワークのテストで使用されています。

  • テストの書きやすいコードを書きましょう。副作用を避けましょう。副作用を抽出しましょう。純粋な関数を書きましょう。

    Why:

    結合を分けてロジックのテストをしたい場合。ランダムで非決定性のプロセスがコードの信頼性に与える影響を最小にする必要があります。もっと読む...

    純粋関数は同じ入力に対して常に同じ結果を出力します。逆に言えば純粋でない関数は副作用をもっているか結果を出力する際に外部の状況に左右されます。そのような関数は予想通りの結果が返ってきにくくなります。もっと読む...

  • 静的解析ツールを使いましょう。

    Why:

    静的解析ツールが必要な場面があるかもしれません。コードが信頼できる基準をもたらしてくれます。

  • developブランチにするリクエストを投げる前にローカルでテストを実行しましょう。

    Why:

    誰しもプロダクション準備中のビルドを失敗される犯人になりたくたいでしょう。rebaseした後、リモートの feature ブランチにリポジトリに Push する前にテストを実行するようにしましょう。

  • テストの実行方法などの情報を含めて、ドキュメントとしてREADME.mdファイルに記述しましょう。

    Why:

    ドキュメントを残すことで他の開発者、DevOps の担当者もしくは QA にプロジェクトを引き継いだ時に、彼らがあなたのコードで仕事をしやすくなります。

6. プロジェクトの構造と名前付け

Structure and Naming

  • ファイルを役割ではなく商品、ページ、コンポーネントのように集約しましょう。テストファイルも実装の隣に配置しましょう。

    Bad

    .
├── controllers
|   ├── product.js
|   └── user.js
├── models
|   ├── product.js
|   └── user.js

    Good

    .
├── product
|   ├── index.js
|   ├── product.js
|   └── product.test.js
├── user
|   ├── index.js
|   ├── user.js
|   └── user.test.js

    Why:

    長いファイルのリストの代わりに、テストコードを含めたカプセル化された単一責任の小さいモジュールが出来上がります。そうすることでコードのガイドがしやすくなり、一目で見つけることができるようになります。

  • 追加のテストファイルは混乱を避けるために test フォルダに置きましょう。

    Why:

    他の開発者やチームの DevOps の担当者の時間を節約することにつながります。

  • ./configフォルダを作成しましょう。違う環境のための違う config ファイルを作らないようにしましょう。

    Why:

    異なる目的(例えばデータベースや API 等々)のために複数の config ファイルに分割する時は、同じフォルダにconfigのようなわかりやすい名前でまとめておきましょう。ただし、異なる環境ごとに異なる config ファイルを作成しないように気をつけてください。新たなデプロイ先が増えた時に新たな環境の名前が必要となり、綺麗にスケールすることができないからです。 config ファイル内の変数は環境変数から与えるのが良い方法です。もっと読む...

  • スクリプトは./scriptsフォルダに置きましょう。ここには node や bash のスクリプトが含まれます。

    Why:

    プロダクション、デベロップのビルド、データベースの構築と同期等々を行う際に少なくとも一つ以上のスクリプトがプロジェクトで必要とされる可能性が高いでしょう。

  • ビルドの成果物は./buildに出力するようにしましょう。build/を.gitignoreに加えましょう。

    Why:    > 名前はなんでもよくて、dist という名前でもかっこいいです。なんでもいいとはいえ、チームのメンバーが矛盾なく理解できる名前でなければなりません。例えば何がそのフォルダで取得できるのか、作成されたものなのかバンドルされたものなのか、コンパイルされたものなのか、もしくはただ移動されてきたものなのか。なにを出力するのか、チームメートがそこになにを出力できるのかもそうです。だからそのフォルダは特殊な事情がない限りですがリモートリポジトリにコミットする必要がありません。

  • PascalCaseとcamelCaseをファイルとディレクトリの名前に使用しましょう。PascalCaseはコンポーネントのみに使用しましょう。

  • CheckBox/index.jsはCheckBoxのコンポーネントを持っているべきです。CheckBox.jsもそうでしょう。しかしCheckBox/CheckBox.jsやcheckbox/CheckBox.jsのような名前は冗長なので避けるべきです。

  • 理想的にはフォルダの名前はindex.jsのデフォルト export の名前と一致させるべきです。

    Why:

    そうすることで親フォルダをシンプルに import するだけでモジュールやコンポーネントを想像できます。

7. コードスタイル

Code style

7.1 コードスタイルガイドライン

  • 新しいプロジェクトでは stage-2 かそれよりバージョンの新しいモダンな JavaScript を使用するようにしましょう。古いプロジェクトについては、モダンな JavaScript が動くプロジェクトにさせたい場合は別として既存のバージョンと互換性のあるバージョンにとどめておきましょう。

    Why:

    チーム次第ではありますが、私たちはトランスパイラを使用することで、新しいシンタックスの利点を活用しています。stage-2 は残りわずかな改訂で仕様の一部になる可能性が徐々に高くなっています。

  • コードスタイルチェックをビルドプロセスに含めましょう。

    Why:

    ビルドを壊すことはコードスタイルを矯正する一つの方法になります。あなたがだんだんコードスタイルを真剣に捉えなくなるということを防いでくれます。クライアントとサーバーサイドのコード両方に導入しましょう。もっと読む...

  • コードスタイルを強制するためにESLint - Pluggable JavaScript linterを使いましょう。

    Why:

    私たちはシンプルな eslint が好きなだけなので、あなたがそうである必要はないです。eslint 自体たくさんのルールをサポートしています。ルールを設定でき、カスタムルールを追加することができます。

  • 私たちはAirbnb JavaScript Style Guideを JavaScript に使っています。もっと読む...。あなたのチームに求められた JavaScript のスタイルガイドを使用しましょう。

  • 私たちはFlowTypeを使用する時にはFlow type style check rules for ESLintを使っています。

    Why:

    Flow には、特定のコードスタイルに従ってチェックする必要がある構文がほとんどありません

  • 特定のフォルダやファイルをコードスタイルチェックから除外するために.eslintignoreを使いましょう。

    Why:

    複数のファイルをスタイルチェックから除外する時に、eslint-disableのコメントでコードを汚す必要がありません。

  • プルリクエストを作成する前にはeslintのコメントアウトを削除しましょう。

    Why:

    ロジックの実装に注力している時はスタイルチェックを無効にするのは一般的ですが、eslint-disable のコメントを削除してルールに従うことを忘れないようにしましょう。

  • タスクのサイズによって、//TODO: コメント使うか、チケットを起票するかを選択しましょう。

    Why:

    チームメートには小さなタスクの事(関数のリファクタリング、コメントのアップデートなど)を定義しておきましょう。大きめのタスクにはリントルール通りに//TODO(#3456)と書き、チケットの番号を記載しましょう。

  • コメントは常にコードの変更に関連させるようにしましょう。コメントアウトされたコードは取り除きましょう。

    Why:

    コードは可能な限り読みやすくする必要があると同時に、余分な部分は除去しておくべきです。リファクタリングする時は既存コードをコメントアウトするのではなく、削除しましょう。

  • 無関係であったりおかしなコードやログや名前付けは避けましょう。

    Why:

    ビルドプロセスでそれらを除去できるかも(すべき)です。あなたのコードは別会社や別クライアントの渡される可能性がありますし、あなたのコードがどこかの誰かに見られて笑われないようにしましょう。

  • 短い名前を避けて、意味として区別しやすい検索しやすい名前をつけましょう。関数には長くて記述的な名前を使いましょう。関数の名前は動詞もしくは動詞のフレーズにしましょう。その関数の意図を伝える必要があります。

    Why:

    ソースコードをより自然により読みやすくさせるためです。

  • ファイル内の関数を降順によってまとめておきましょう。高いレベルの関数は上部へ、低いレベルの関数は下部へ位置させましょう。

    Why:

    読むのに適したソースコードになるようにするためです。

7.2 標準的なコードスタイルの強制

  • .editorconfig ファイルを使って開発者が異なるエディタや IDE のプロジェクト間で一貫したコーディングスタイルを定義し維持することができるようにしましょう。

    Why:

    EditorConfig プロジェクトはコーディングスタイル定義とエディタがファイルフォーマット読み込んでスタイル定義を有効にするエディタプラグインからなります。EditorConfig ファイルは可読性が高くバージョンコントロールシステムともうまく機能します。

  • コードスタイルのエラーを伝えてくれるエディタを使いましょう。既存の ESLint の設定と一緒にeslint-plugin-prettierとeslint-config-prettierを使いましょう。もっと読む...

  • Git hook の使用を考えましょう。

    Why:

    Git hook は開発者の生産性を大きく高めてくれます。ビルドの破壊を怖がることなく、ステージングやプロダクション環境に変更を作成、コミット、Push できます。もっと読む...

  • Prettier をprecommit hookとともに使いましょう。

    Why:

    prettier自体はとても力強いものではありますが、毎回のコードフォーマットに対して個別の npm task としてシンプルに実行することはあまり生産的ではありません。ここではlint-staged(とhusky)が活躍します。lint-staged hereのhusky hereの設定をよく読みましょう。

8. ログ

Logging

  • クライアントサイドの console ログをプロダクション環境で出力するのは避けましょう。

    Why:

    ビルドプロセスを通して Console ログを取り除くことができます(すべきです)が、コードスタイルチェックが吐き出す console log についての warning の情報を確認しましょう。

  • プロダクションのログは読みやすいように出力しましょう。理想的にはプロダクションモードで使われているロギングライブラリを使いましょう(winston もしくは node-bunyanのようなものがあります。)

    _Why:_
> ログのカラー化やタイムスタンプ、ログファイルの出力や日々のログファイルのローテートが、トラブルシューティングの不快感を少なくしてくれます。

9. API

API

9.1 API デザイン

Why:

私たちは明快に構築された RESTful のインターフェースでの開発を強制することで、チームメンバーやクライアントがシンプルに矛盾なくそれを使えることができます。

Why:

一貫性やシンプルさがない API はシステムの結合やメンテナンスのコストを増加させます。だからAPI designをこのドキュメントに含めて説明しています。

  • 私たちは多くの場面でリソース志向アーキテクチャに従っています。リソース志向アーキテクチャとは主にリソース、集合、URL の要素で構成されます。

    • リソースはデータを持っていて、ネストを取得でき、それらのリソースを操作できるメソッドがあります。
    • リソースの集合はコレクションと呼ばれます。
    • URL はオンラインのリソースの場所はリソースかコレクションで表します。

    Why:

    上記のことは開発者(あなたの API を使う人たち)に周知されていることです。可読性や使いやすさを別としても、REST API ではその API の詳細を知らずとも汎用なライブラリやコネクタを書くができます。

  • URL には kebab-case を使いましょう。

  • リクエスト内のパラメータやリソース内のパラメータには camelCase を使いましょう。

  • URL 内のリソース名は複数形の kebab-case にしましょう

  • コレクションを表す url には常に複数形の名詞を使いましょう。/users

    Why:

    基本的にはそうすることで読みやすさの向上 URL の一貫性を維持することになるでしょう。もっと読む...

  • ソースコード内での変数やプロパティ名の複数形はリストのサフィックスにしましょう。

    Why:

    複数形は URL においては良いものですが、ソースコード内では分かりにくくエラーの原因になり得ます。

  • コレクションで始まり識別子に終わる単一のパスを常に使用しましょう。

    /students/245743
/airports/kjfk

  • 以下のような URL は避けましょう。

    GET /blogs/:blogId/posts/:postId/summary

    Why:

    この URL はリソースではなく、プロパティをさしています。プロパティはレスポンスを整えるようにパラメータに渡しましょう。

  • リソースを示す URL からは動詞を含めないようにしましょう。

    Why:

    各リソースの操作に動詞を含めると、各々のリソースの操作について大量の URL が出来てしまい、開発者にとって理解するのが難しい一貫性のないパターンになってしまうからです。私たちは他の箇所に動詞を使っています。

  • リソースではない部分に動詞を使用しましょう。このケースではこの API はリソースを返さずに、操作を実行して結果を受け取るのみです。CRUD(Create Retrieve Update Delete)の操作ではないことに注意しましょう。

    /translate?text=Hallo

    Why:

    CRUD についてはリソースやコレクションの URL に対して HTTP メソッドを使用するからです。説明している動詞はおおよそControllerとなります。通常これらの URL をたくさん作成することはないでしょう。もっと読む...

  • リクエストボディやレスポンスタイプはJSONにしましょう。そして一貫性あるメンテナンスをしやすくするために、プロパティ名はcamelCaseを使用するようにしましょう。

    Why:

    このドキュメントは JavaScript プロジェクトのガイドラインであるため、JSON の読み書きには JavaScript が使用されてることを想定しています。

  • リソースオブジェクトインスタンスや DB のレコードと同じような単一なものであったとしても、table_nameやcolumn_nameはリソース名やプロパティ名にしないようにしましょう。

    Why:

    あくまでリソースを公開するのであって DB のスキーマの詳細を公開するためのものではないからです。

  • 念のためにもう一度、URL には名詞のみを使い、機能を説明するような名前付けは避けましょう。

    Why:

    名詞のみをリソースの URL には使用しましょう。/addNewUserや/updateUseのようなエンドポイントを用意するのはやめましょう。同様にリソース操作をパラメータを送るのも避けましょう。

  • CRUD の機能的説明には HTTP のメソッドを使いましょう。

    How:

    GET: 存在するリソースの取得。

    POST: 新しいリソースとサブリソースの作成。

    PUT: 既存のリソースの更新。

    PATCH: 既存のリソースの更新。提供されたフィールドのみを更新し、他のフィールドはそのままにしておきます。

    DELETE: 存在するリソースの削除。

  • ネストしているリソースのために関連する URL 間にリレーションを使用しましょう。例えば会社の従業員を関連されるために、id を使用します。

    Why:

    各リソースを探索しやすくするための自然なやり方です。

    How:

    GET /schools/2/students 。2 の学校のすべての生徒を取得できるはずです。

    GET /schools/2/students/31 。2 の学校に所属する、31 の生徒の詳細を取得できるはずです。

    DELETE /schools/2/students/31 。2 の学校に所属する 31 の生徒を削除できるはずです。

    PUT /schools/2/students/31 。31 の生徒の情報を更新するはずです。また PUT はコレクションには使用せずにリソース URL のみに使用するようにしましょう。

    POST /schools。新たな学校を作成して、その作成された学校の情報を返却するはずです。POST はコレクションの URL に使用しましょう。

  • バージョンにはvをプレフィックスとした単純な整数を使用しましょう(v1,v2)。全ての URL を残したまま移動するために、バージョンは一番上のスコープに使用しましょう。

    http://api.domain.com/v1/schools/3/students

    Why:

    API がサードパーティのために公開される時には、API の破壊的変更を伴うバージョンアップは既存のプロダクトや API を使うサービスに多大な影響を与えます。バージョンを URL に含めることで、これらの問題が起きることを防いでくれます。もっと読む...

  • レスポンスメッセージは自己記述的でなければなりません。良いエラーレスポンスは以下のようなものになります。

    {
	"code": 1234,
	"message": "Something bad happened",
	"description": "More details"
}

    またバリデーションエラーならこうです。

    {
	"code": 2314,
	"message": "Validation Failed",
	"errors": [
		{
			"code": 1233,
			"field": "email",
			"message": "Invalid email"
		},
		{
			"code": 1234,
			"field": "password",
			"message": "No password provided"
		}
	]
}

    Why:

    API を使用したアプリケーションがそのユーザーの手元に届けられたあと、問題解決やトラブルシューティングをする重要な時に、開発者は良いデザインのエラーメッセージに頼ることになります。

    Note: セキュリティの例外のメッセージは極力一般化しましょう。例えば"パスワードが間違っています"と言う代わりに、"ユーザー名もしくはパスワードが間違っています"と言いましょう。私たちの場合はユーザー名が正しくて、パスワードだけ間違っていると伝えることはしないようにしています。

  • 全てがうまく動いていた、クライアントアプリがうまく動いてなかった 、API がうまく動いてなかった 等 レスポンスの説明には 8 個のステータスのみを送るようにしましょう。

    _一覧:_
> `200 OK` `GET`、`PUT` 、`POST`リクエストが成功したことを表します。

> `201 Created` 新しいインスタンスが作成された時に返却されます。新しいインスタンスの作成、`POST`メソッドの使用は`201`のステータスコードを返します。

> `304 Not Modified` ユーザーがすでにレスポンスのキャッシュを持っている場合に返却されます、最小の転送に抑えることになります。

> `400 Bad Request` リクエストが処理されなかった場合に返却されます。サーバーがクライアントの要求するリクエストを理解できなかったような時です。

> `401 Unauthorized` リクエストの認証情報が不足している時に返却されます。要求された認証情報で再リクエストを行うことになるでしょう。

> `403 Forbidden` サーバーはリクエストを解釈できていますが、認証を拒否したという意味です。

> `404 Not Found` リクエストしたリソースが見つからなかったことを示します。

> `500 Internal Server Error` リクエストは正しいが、サーバーが予期せぬ事態により動作しなかったことを示します。

_Why:_
> 多くのAPIの提供者は少数のHTTPのステータスコードを使用します。例えばGoogleのGdata APIは10個のステータスコードしか使っていません。Netflixは9つです。Diggは8つだけです。もちろんながらこれらのレスポンスは追加の情報をbodyに含めています。70を超えるHTTPのステータスが存在しますが。あまり一般的でないステータスコードを選択すると、アプリケーションの開発者は開発を離れて、ステータスコードが何を示しているのかを理解しようとwikipedia等で調べざるを得なくなります。[もっと読む...](https://apigee.com/about/blog/technology/restful-api-design-what-about-errors)

  • レスポンスにはリソースの数の合計を提供しましょう。

  • limitとoffsetのパラメータを受けつけましょう。

  • リソースの公開するデータ量はよく考える必要があります。API の利用者は常にリソースの全ての表現が必要というわけではありません。フィールドのカンマ区切りリストを含むフィールドクエリパラメータを使用します。

    GET /student?fields=id,name,age,class

  • ページネーション、フィルタリング、ソートは初めから全てのリソースをサポートする必要はありません。フィルタリングやソートのあとにこれらのリソースを記述しましょう。

9.2 API セキュリティ

いくつかのセキュリティのベストプラクティスをご紹介します。

  • セキュアな通信(HTTPS)以外ではベーシック認証を使わないようにしましょう。認証トークンを URL に含めてはいけません。GET /users/123?token=asdf....

    Why:

    トークンやユーザー ID やパスワードが平文としてネットワークを超えてくるので（base64 にエンコードされているでしょうが、base64 は可逆なエンコード方法です。）、ベーシック認証機構はセキュアではないです。もっと読む...

  • トークンは毎回のリクエストの認証ヘッダーに乗せて送信されなければなりません。Authorization: Bearer xxxxxx, Extra yyyyy

  • 認証コードの生存期間は短く設定されるべきです。

  • 安全ではないデータの受け渡しを避けるために HTTP リクエストに応答しないことで TLS ではないリクエストを拒否するようにしましょう。その際には403 Forbiddenで応答しましょう。

  • リクエスト制限を使うことを考えましょう。

    Why:

    一時間あたり何千ものリクエストを送りつけてくるボットから身を守るために、リクエスト制限を早いうちから考えておくべきでしょう。

  • HTTP ヘッダを適切に設定することは Web アプリケーションをより強固に、より安全にするのに役立ちます。もっと読む...

  • API は標準的なフォームのデータを受け取ってデータを加工しましょう。できなければリクエストを拒否するようにしましょう。400 Bad Request とともにデータの不足やエラーについての詳細を返却しましょう。

  • REST な API で交換される全てのデータは API 上で Validate するようにしましょう。

  • JSON をシリアライズしましょう。

    Why:

    JSON エンコーダの悩みの種は、ブラウザ内でリモートからの任意の JavaScript の実行を防ぐことです。もしくは node.js を使用しているのであれば、サーバーサイドも同様です。ユーザーから与えられた入力がブラウザ内で実行されないように、ユーザーからの情報をエンコードできる適切な JSON シリアライザーを使用することが重要です。

  • Content-Type を Validate するようにしましょう。多くの場合で application/*json (Content-Type ヘッダ)を使いましょう。

    Why:

    例えば、application/x-www-form-urlencodedの mime-type を受け入れることは、攻撃者にフォームを作成させ、シンプルな POST リクエストを誘引させることを許すことになります。サーバは受け入れる Content-Type を決して推定させないべきです。Content-Type ヘッダもしくは予期しない Content-Type ヘッダに対しては4XXのレスポンスでリクエストを拒否する結果を返却しましょう。

  • API のセキュリティをチェックリストを見て確認しましょう。もっと読む...

9.3 API ドキュメント

  • README.md templateのAPI Referenceのセクションを埋めましょう。
  • コードのサンプルとともに API の認証方法について記述しましょう。
  • URL の構造(path についてのみでいいです。root の URL については必要ありません。)をリクエストのメソッドとともに説明しましょう。

各エンドポイントについて

  • URL パラメータはもし存在する場合は、URL セクションに記載されている名前に従って指定しましょう。

    Required: id=[integer]
Optional: photo_id=[alphanumeric]

  • リクエストタイプが POST なら、ちゃんと動く例も用意しましょう。URL パラメータのルールはここにも適用します。Optional と Required に分けましょう。

  • レスポンスの成功の場合ステータスコードは何でしょうか？どんなデータを返されるでしょうか？ドキュメントは API の返答を開発者が知りたいときに役立ちます。

    Code: 200
Content: { id : 12 }

  • レスポンスの失敗の時は、ほとんどのエンドポイントの失敗は複数通りあります。認証されていないアクセスからの不正な値等。それら全てをここでは列挙しましょう。繰り返しになりますが、こうすることで憶測のみで開発せざるを得ない状況を防ぎます。例

    {
	"code": 403,
	"message": "Authentication failed",
	"description": "Invalid username or password"
}

  • API デザインツールを使用しましょう。API Blueprint、Swaggerのようなオープンソースの良いドキュメンテーションツールがたくさんあります。

10. ライセンス

Licensing

使用できる権利のあるリソースを使用していることを確認してください。ライブラリを使っているのであれば、MIT、Apache、BSD のライセンスを見つけることを心がけましょう。ライブラリを修正したいのであれば、ライセンスの詳細を少し見て見ましょう。著作権で保護されている画像や動画が法的問題を引き起こすかもしれません。

Sources: RisingStack Engineering, Mozilla Developer Network, Heroku Dev Center, Airbnb/javascript, Atlassian Git tutorials, Apigee, Wishtack

Icons by icons8