API は、アプリケーションまたはコンポーネント間の通信のためのプログラミング インターフェイスです。 API は、プライベートとパブリックに分けられます。プライベート API は、たとえば、相互に通信する複数のソフトウェア製品がある場合に、企業内で使用されます。パブリック API は、サードパーティの開発者が使用できます。確かに、場合によっては支払う必要があります。ただし、API の品質と使いやすさに対するユーザーの要件も高くなります。
API サービスが公開されると、奇跡は起こりません。ユーザー数は増えておらず、通常、この機能を有料にすることは忘れてしまいます (積極的な広告を伴うマーケティングの嘘のために製品が宣伝されている場合は除きます)。
そして、企業の収入がパブリック API に直接依存している場合、そのリスクは非常に高くなります。このアイデアについては、「API 継続的な開発」という本で詳しく説明されています。変化する技術環境における正しい決定」(Mehdi Medjui、Ronnie Mitra など):
我々はさらに行きます...
開発者は、主にAPIで実装されたすべての計画機能を得ることに集中することができます。しかし、完全に満たされていないことが多く、特別な注意が必要な「機能しない」要件があります。
私の意見では、すべての API について、次の非機能要件が高品質で満たされることが不可欠です。
- 安全性
- ドキュメンテーション
- 検証
- テスト
安全性
安全性が優先された理由を説明する価値はおそらくないでしょう。私は 4 つの最も重要なセキュリティ上の課題を特定しました。
- SSL 証明書での HTTPS の使用
- さまざまなソース (CORS) からのリソースの共有
- 認証と JSON Web トークン
- 認可とアクセス権限
※以下、コンテキストをRESTとJSON APIに絞り込みます。
1. SSL 証明書で HTTPS を使用する
SSL 証明書を使用する HTTPS は、今や事実上のセキュリティ標準です。証明書を生成するために、私は個人的にLet's Encrypt を使用します。これ は、非営利の Internet Security Research Group (ISRG) が提供する無料の自動 CA です。
これらの証明書により、API からユーザーに送信されるデータが確実に暗号化されます。
2. 異なるソース (CORS) からのリソースの共有
他のソースへのリクエストを安全に保つために、ブラウザは CORS と呼ばれるメカニズムを使用します。 CORS は Cross-Origin Resource Sharing の略で、さまざまなソースからのリソースを共有するためのテクノロジーです。ブラウザーは (同じソース ルールのおかげで) 異なるソースからのリソースへのアクセスを許可しませんが、CORS を使用すると、これらの制限を回避し、同時にリソースへのアクセスが安全であることを確認できます。
ユーザーエージェント (ブラウザーなど) は、HTTP リクエストの CORS の追加ヘッダーの値に基づいて、CORS なしではブロックされる他のソースにリクエストを行うことができます。
ここにあります 例：アン
からのサーバーで提供するHTMLページ http://domain-a.comは要求 SRCを で http://domain-b.com/image.jpg。
多くのページは、CSS スタイル、画像、スクリプトなどのリソースを、さまざまな CDN (コンテンツ配信ネットワーク) に対応するさまざまなドメインから読み込みます。 Node.js 用の CORS
実装は、現在非常に人気があります 。
3. 認証と JSON Web トークン (JWT)
API ユーザー認証にはいくつかのアプローチがありますが、最良の方法の 1 つは JWT を使用することです。これらのトークンは、さまざまな暗号化アルゴリズムを使用して署名されます。
JSON Web Token は、JSON 形式に基づいてアクセス トークンを作成するためのオープン スタンダードです。通常、クライアント サーバー アプリケーションで認証データを渡すために使用されます。
トークンを作成するには、トークンに関する一般情報、ペイロード (ユーザー ID、ロールなど)、および署名を含むヘッダーを定義する必要があります。簡単に言えば、JWT は次の形式の header.payload.signature の単なる文字列です。
クライアントがログオンすると、ID 管理サービスは JWT をクライアントに提供します。その後、クライアントはこのトークンを使用して API リクエストを行うことができます。 API は、トークンの検証に使用する公開鍵または秘密にアクセスできます。
検証には、たとえばjsonwebtokenライブラリを使用できます 。以下は JavaScript コードです:
import jwt from 'jsonwebtoken'
export default function (req, res, next) {
// req.headers.authorization Bearer token
const token = extractToken (req)
jwt.verify (token, SECRET, {algorithms: ['HS256']}, (エラー、デコード済み) => {
if (err) {next (err)}
req.session = Decoded
next ()
})
}
JWT、ライブラリ、サポートされているプログラミング言語に関する詳細情報 - オンライン JWT.io。
4. 認可とアクセス権限
認証は重要ですが、承認も同様に重要です: JWT を認証して受信したクライアントは、特定のリクエストを実行する権限を持っていますか?
これをテストするには、スコープを使用します。それを分析することにより、API サービスは、コストのかかる ACL ルックアップなしでこのクライアント要求を満たすことができるかどうかを判断します。
スコープは、API エンドポイントのアクセス権限を説明するテキスト ブロック (通常はスペースで区切られます) です。それらに適用できるリソースとアクションについて説明します。この形式化は、構造が非常に類似しているため、REST / JSON API に適しています。
リソース: アクション (たとえば、ARTICLE: WRITE または ARTICLE: READ、ここで ARTICLE はリソース、READ および WRITE はアクション)。
これにより、API 開発者はロールやユーザーではなく機能に集中できます。ID 管理サービスは、ロールとユーザーを特定のスコープに関連付け、JWT とともに、scop をクライアントに送信できます。
安らかに眠るために
API を開発およびデプロイする場合、セキュリティは常に最も重要な要件の 1 つです。もちろん、それについて延々と話したり書いたりすることはできますが、実稼働環境で説明されている 4 つのタスクを適切に実装することで、すでによく眠ることができます。
ドキュメンテーション
ドキュメントの欠如よりも悪いことは何ですか? 古いドキュメントです。
開発者はドキュメントについてあいまいです。多くの人は、明らかにこのビジネスをあまり愛していません。それはともかく、このタスクは非常に重要です。特に、パブリック API の場合はそうです。サードパーティの開発者は、その使用方法を学習できるはずです。さらに、優れたドキュメントは、チームに参加する新しい開発者をより迅速にトレーニングするのに役立ちます。
API ドキュメントには、次の 3 つの基本的なセクションを含める必要があります。
- はじめに（README）
- データシート（仕様）
- 使用例 (入門およびその他の類似のサブセクション)
1. README
ドキュメントでは、API の目的、環境のセットアップ方法、サービスのテスト方法、プロジェクトのデプロイ方法について説明する必要があります。もちろん、ユーザーは、困難や問題を報告する方法と場所も知っている必要があります。
これは README ファイルに書かれています。このファイルは通常、リポジトリにも配置され、開発者がプロジェクトで作業するための開始点となります。
README には次の内容を含める必要があります。
- API 説明
- テクニカル リファレンスとマニュアルへのリンク
- 開発者向け設定ガイド
- テスターガイド
- 導入ガイド
- 依存関係管理
- 寄稿者ガイド
- 行動規範
- ライセンス
- ありがとう
README は簡潔にしてください。すべてのニュアンスを説明する必要はありませんが、開発者がプロジェクトに取り掛かるのに十分な情報を提供してください。
2. 仕様
REST / JSON API では、各エンドポイントは特定の目的のために構築された関数です。各エンドポイント、入力と出力、およびサービスがさまざまなクライアントでどのように機能するかを説明する技術文書を用意することが重要です。 OpenAPI に
基づいて独自の API ドキュメントを作成できます 。 これは、REST Web サービスを記述、作成、使用、およびレンダリングするための仕様および完全なフレームワークです。その仕事は、ドキュメント システムが更新をサーバー上の変更と同期できるようにすることです。メソッド、パラメーター、モデル、およびその他の要素は、OpenAPI を介してサーバー ソフトウェアと統合され、常に同期されます。
3. 使用例
API ユーザーに仕様をぶつけただけでは、API ユーザーが満足することはまずありません。彼らは、特定の状況で API を使用する方法と、一般的な問題を解決する方法を知りたがっています。ほとんどの潜在的なユーザーは問題を抱えており、それらを解決するために API を利用します。
API をユーザーに紹介する優れた方法は、Getting Started サブセクションを作成することです。これは、典型的なユースケースを理解し、それらを使用して API の利点を評価するのに役立ちます。
3頭のクジラ
ドキュメントは、あらゆる API の重要なコンポーネントです。ドキュメントを書くときは、API ドキュメントを成功させるための 3 つの柱である README、仕様、ユースケースに留意してください。そして、あなた (そしてあなたのユーザー) は幸せになるでしょう!
データ検証
API 開発の重要な側面であるデータ検証は、多くの場合見過ごされています。検証は、外部ソースからの入力を検証するプロセスです。これらのソースは、JSON を送信するクライアント、またはリクエストに応答するサービスです。このチェックにより、データが正確であることを確認します。そのおかげで、多くの潜在的な問題を解決できます。検証の重要なタスクは、入力データに必要な形式と値の範囲、およびそれを制御する方法を理解することです。
最善の戦略は、サービスがデータ操作を実行する前に検証を実行することです。クライアントがメール、日付、名前などのデータを API に送信するときは、それが実際にメール アドレスであること、日付が正しくフォーマットされていること、文字列が長さの要件を満たしていることを確認してください。この簡単なチェックにより、サービスがより安全で整理されたものになります。
また、ある種のデータベースまたはキャッシュからサービスからデータを取得する場合は、それを再確認して、返される結果が期待どおりであることを確認してください。
検証は手動で実装できますが、Lodashや Ramdaなどのライブラリをこの目的に使用することもでき ます。... それらは小さなデータ オブジェクトに最適です。以下のようなライブラリ 攘夷、 うん、または ZODのより良い仕事は、彼らはあなたがあなたの時間と労力を節約、一般的な検証フレームワークを記述することができますので。特定のプログラミング言語に依存しないものが必要な場合は、JSON Schema を参照してください 。
控えた方がいい
検証は楽しいことではありませんが、トラブルシューティングやデータ移行スクリプトの作成に費やす時間を大幅に節約できます。ビジネス ロジックやストレージに不正なデータが入り込まないようにするには、クライアントが未検証のデータを送信すると信頼するという間違いをしないでください。
少し時間を取って、入力の検証を手配してください。ことわざにあるように、それを逃すよりはやり過ぎる方が良いです。
テスト
テストは、ソフトウェア ライフ サイクルの不可欠な部分です。私たちの場合、それは重要な非機能要件の 1 つとして認識されるべきです。テスト戦略の定義は、サービス API を含め、どのプロジェクトにとっても困難な作業です。常に自分の限界を認識し、それに応じて戦略を定義するようにしてください。
統合テストは、最も効果的な API テスト方法の 1 つです。そのタスクは、アプリケーションがある状態から別の状態に正しく遷移することを確認することです。私たちの場合、一連の統合テストには、サービス API エントリ ポイントのテストと、サービスへのリクエストの送信とレスポンスの受信をシミュレートするためのモックアップが含まれている必要があります。これが、私たちのサービスのメイン テスト ケースをチェックする方法です。
この方法では、バックエンド サービスの内部構造やデータ表示ロジックを考慮せずに、データ処理ロジックのみに集中できます。依存関係がないため、テストの実行の信頼性が高まり、自動化が容易になり、継続的インテグレーション パイプラインに組み込みやすくなります。
統合テストには、 Tape、 Test-server、および Fetch-mock を使用します。これらのライブラリを使用すると、リクエストからレスポンスまで、API エンドポイントに対して分離されたテストを実行できます。
模倣ゲーム
他の種類のテストと型チェックも確かに役立ちますが、統合テストには最大の利点があります。つまり、テストの作成と保守に費やす工数が少なくて効率が高くなります。また、Fetch-mock などのツールを使用すると、データ交換の完全なシミュレーションを提供できます。
止まらないで
4 つの非機能要件をすべて完了したら、そこで止まらないでください。他にもいくつかあります: アプリケーションのモニタリング、ロギング、API 管理。ただし、いずれにせよ、セキュリティ、ドキュメント、検証、およびテストが最初に行われる必要があります。
Macleod のクラウド サーバー は高速で安全です。
上記のリンクを使用するか、バナーをクリックして登録すると、任意の構成のサーバーをレンタルした最初の 1 か月間で 10% の割引が受けられます。
