RESTAPIを作成するためのベストプラクティス

こんにちは！



この記事は、その無実のタイトルにもかかわらず、Stackoverflowに関する非常に冗長な議論を引き起こしたため、無視することはできませんでした。広大さを把握する試み（REST APIの有能な設計について明確に伝えるため）は、明らかに、著者は多くの方法で成功しましたが、完全ではありませんでした。いずれにせよ、私たちは、エクスプレスファンの軍隊に加わるという事実だけでなく、議論の程度においてオリジナルと競争したいと思っています。



読書を楽しむ！



REST APIは、現在利用可能な最も一般的なタイプのWebサービスの1つです。彼らの助けを借りて、ブラウザアプリケーションを含むさまざまなクライアントは、RESTAPIを介してサーバーと情報を交換できます。



したがって、途中で問題が発生しないように、RESTAPIを正しく設計することが非常に重要です。消費者の観点から、APIのセキュリティ、パフォーマンス、および使いやすさを検討してください。



そうしないと、APIを使用しているお客様に問題が発生します。これは苛立たしくて煩わしいことです。一般的な規則に従わない場合、アーキテクチャは誰もが期待するものとは異なるため、APIを維持する人と顧客を混乱させるだけです。



この記事では、REST APIを使用するすべての人にとってシンプルで理解しやすいように、RESTAPIを設計する方法について説明します。このようなAPIを介してクライアントに送信されるデータは機密情報である可能性があるため、耐久性、セキュリティ、および速度を確保します。



ネットワークアプリケーションが失敗する理由とオプションは多数あるため、REST APIのエラーが適切に処理され、消費者が問題に対処できるように標準のHTTPコードが付随していることを確認する必要があります。

JSONを受け入れ、応答としてJSONを返します

REST APIは、要求ペイロードのJSONを受け入れ、JSON応答も送信する必要があります。 JSONはデータ転送標準です。ほとんどすべてのネットワークテクノロジーがそれを使用するように適合されています。JavaScriptには、FetchAPIまたは別のHTTPクライアントを介してJSONをエンコードおよびデコードするための組み込みメソッドがあります。サーバー側のテクノロジーは、ライブラリを使用してJSONをデコードしますが、ユーザーの介入はほとんどまたはまったくありません。



データを転送する方法は他にもあります。 XML自体は、フレームワークではあまり広くサポートされていません。通常、データをより便利な形式（通常はJSON）に変換する必要があります。クライアント側、特にブラウザでは、このデータを処理するのはそれほど簡単ではありません。通常のデータ転送を保証するためだけに、多くの追加作業を行う必要があります。



フォームは、特にファイルを転送する場合に、データを転送するのに便利です。ただし、テキストおよび数値形式で情報を転送する場合、ほとんどのフレームワークでは追加の処理なしでJSON転送が可能であるため、フォームなしで実行できます。クライアント側でデータを取得するだけです。これは、それらに対処するための最も簡単な方法です。



クライアントがRESTAPIから受信したJSONをJSONとして正確に解釈できるようにするには、要求が行われた後、Content-Type応答ヘッダーを値application/jsonに設定します。多くのサーバー側アプリケーションフレームワークは、応答ヘッダーを自動的に設定します。一部のHTTPクライアントContent-Typeは、応答ヘッダーを調べ、そこで指定された形式に従ってデータを解析します。



唯一の例外は、クライアントとサーバー間で転送されるファイルを送受信しようとしたときに発生します。次に、応答として受信したファイルを処理し、フォームデータをクライアントからサーバーに送信する必要があります。しかし、これは別の記事のトピックです。



また、JSONがエンドポイントからの応答であることを確認する必要があります。多くのサーバーフレームワークには、この機能が組み込まれています。



JSONペイロードを受け入れるAPIの例を見てみましょう。この例では、Node.js用のExpressバックエンドフレームワークを使用しています。プログラムをミドルウェアとして使用しbody-parserてJSONリクエストの本文を解析res.jsonし、JSONレスポンスとして返したいオブジェクトを使用してメソッドを呼び出すことができます。これは次のように行われます。

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.post('/', (req, res) => {
  res.json(req.body);
});

app.listen(3000, () => console.log('server started'));

bodyParser.json()リクエスト本文の文字列をJSONに解析し、JavaScriptオブジェクトに変換してから、結果をオブジェクトに割り当てますreq.body。



応答のContent-Typeヘッダーをapplication/json; charset=utf-8変更せずに値に設定します。上記の方法は、他のほとんどのバックエンドフレームワークに適用できます。

動詞ではなく、エンドポイントへのパスに名前を使用します

エンドポイントへのパスの名前は、動詞ではなく名前にする必要があります。この名前は、そこから取得する、または操作するエンドポイントのオブジェクトを表します。



重要なのは、HTTPリクエストメソッドの名前にはすでに動詞が含まれているということです。 APIエンドポイントへのパスの名前に動詞を入れることは実用的ではありません。さらに、名前が不必要に長く、貴重な情報が含まれていないことが判明しました。開発者が選んだ動詞は、彼の気まぐれに応じて簡単に置くことができます。たとえば、「get」オプションを好む人もいれば、「retrieve」を好む人もいるので、エンドポイントが何をしているのかを正確に伝えるおなじみのHTTPGET動詞に限定することをお勧めします。



アクションは、作成するリクエストのHTTPメソッドの名前で指定する必要があります。最も一般的なメソッドには、動詞GET、POST、PUT、およびDELETEが含まれています。

GETはリソースをフェッチします。POSTは新しいデータをサーバーに送信します。PUTは既存のデータを更新します。DELETEはデータを削除します。これらの各動詞は、CRUDグループの操作の1つに対応します。



上記の2つの原則を考慮すると、新しい記事を受け取るには、GET形式のルートを作成する必要があります/articles/。同様に、POSTを使用/articles/して新しい記事 /articles/:id を更新し、PUTを使用して特定の記事で記事を更新しますid。DELETEメソッドは /articles/:id、指定されたIDを持つ記事を削除するように設計されています。



/articlesRESTAPIリソースです。たとえば、Expressを使用して、記事で次のことを行うことができます。

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.get('/articles', (req, res) => {
  const articles = [];
  //    ...
  res.json(articles);
});

app.post('/articles', (req, res) => {
  //     ...
  res.json(req.body);
});

app.put('/articles/:id', (req, res) => {
  const { id } = req.params;
  //    ...
  res.json(req.body);
});

app.delete('/articles/:id', (req, res) => {
  const { id } = req.params;
  //    ...
  res.json({ deleted: id });
});

app.listen(3000, () => console.log('server started'));

上記のコードでは、記事を操作するためのエンドポイントを定義しました。ご覧のとおり、パス名には動詞がありません。名前のみ。動詞は、HTTPメソッドの名前でのみ使用されます。



POST、PUT、およびDELETEエンドポイントは、JSON要求本文を受け入れ、GETエンドポイントを含むJSON応答も返します。

コレクションは複数の名詞と呼ばれます

コレクションには、複数の名詞を付けて名前を付ける必要があります。コレクションから1つのアイテムだけを取得する必要があることはめったにないため、一貫性を保ち、コレクション名に複数の名詞を使用する必要があります。



複数は、データベースの命名規則との一貫性を保つためにも使用されます。原則として、テーブルには1つではなく多くのレコードが含まれ、それに応じてテーブルに名前が付けられます。



エンドポイント/articlesを操作する場合、すべてのエンドポイントに名前を付けるときに複数を使用します。

階層オブジェクトを操作するときのリソースのネスト

ネストされたリソースを処理するエンドポイントのパスは、次のように構成する必要があります。ネストされたリソースを、親リソースの名前に続くパス名として追加します。

コード内のリソースのネストが、データベーステーブル内の情報のネストとまったく同じであることを確認する必要があります。そうしないと、混乱が生じる可能性があります。



たとえば、特定のエンドポイントで新しい記事に関するコメントを受け取りたい場合は、パス/コメントをパスの最後に添付する必要があります/articles。この場合、commentsエンティティをarticleデータベース内の子エンティティと見なすと想定されています。



たとえば、Expressで次のコードを使用してこれを行うことができます。

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.get('/articles/:articleId/comments', (req, res) => {
  const { articleId } = req.params;
  const comments = [];
  //      articleId
  res.json(comments);
});


app.listen(3000, () => console.log('server started'));

上記のコードでは、パスでGETメソッドを使用できます'/articles/:articleId/comments'。comments一致する記事へのコメントを受け取りarticleId、返信します。'comments'パスセグメントの後に追加して'/articles/:articleId'、これが子リソースであることを示します/articles。



コメントは子オブジェクトでarticlesあり、各記事には独自のコメントのセットがあると想定されているため、これは理にかなっています。そうしないと、この構造は通常、子オブジェクトにアクセスするために使用されるため、ユーザーを混乱させる可能性があります。POST、PUT、およびDELETEエンドポイントを操作する場合も同じ原則が適用されます。これらはすべて、パス名を作成するときにネストする同じ構造を使用します。

きちんとしたエラー処理と標準エラーコードを返す

APIでエラーが発生したときの混乱を避けるために、エラーを慎重に処理し、発生したエラーを示すHTTP応答コードを返します。これにより、APIメンテナは問題を理解するのに十分な情報を得ることができます。エラーがシステムをクラッシュさせることは許容できないため、エラーを処理せずに残すことはできず、APIコンシューマーはそのような処理を処理する必要があります。



最も一般的なHTTPエラーコードは次のとおりです。

• 400 BadRequest-クライアントから受信した入力が検証に失敗したことを示します。
• 401 Unauthorized-ユーザーがログインしていないため、リソースにアクセスする権限がないことを意味します。通常、このコードは、ユーザーが認証されていないときに発行されます。
• 403 Forbidden-ユーザーは認証されていますが、リソースにアクセスする権限がないことを示します。
• 404 NotFound-リソースが見つからなかったことを意味します
• 500内部サーバーエラーはサーバーエラーであり、明示的にスローしないでください。
• 502 BadGateway-アップストリームサーバーからの無効な応答メッセージを示します。
• 503 Service Unavailable-サーバー側で予期しないことが発生したことを意味します-たとえば、サーバーの過負荷、一部のシステム要素の障害など。

アプリケーションを妨げたエラーに対応するコードを正確に発行する必要があります。たとえば、リクエストペイロードとして受信したデータを拒否する場合、Express APIのルールに従って、次の400のコードを返す必要があります。

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

//  
const users = [
  { email: 'abc@foo.com' }
]

app.use(bodyParser.json());

app.post('/users', (req, res) => {
  const { email } = req.body;
  const userExists = users.find(u => u.email === email);
  if (userExists) {
    return res.status(400).json({ error: 'User already exists' })
  }
  res.json(req.body);
});


app.listen(3000, () => console.log('server started'));

上記のコードでは、users配列に、電子メールを知っている既存のユーザーのリストを保持しています。



さらに、emailユーザーにすでに存在する値でペイロードを送信しようとすると、コード400の応答と、'User already exists'そのようなユーザーがすでに存在することを示すメッセージが表示されます。この情報を使用して、ユーザーはより良くなることができます-電子メールアドレスをまだリストにないものに置き換えます。



エラーコードには、エラーを修正するのに十分な情報を提供するメッセージを常に添付する必要がありますが、情報を盗んだりシステムをクラッシュさせたりする攻撃者がこの情報を使用する可能性があるほど詳細ではありません。



APIが適切にシャットダウンに失敗した場合は常に、ユーザーが状況を修正しやすくするために、エラー情報を送信して失敗を慎重に処理する必要があります。

データの並べ替え、フィルタリング、ページネーションを許可する

RESTAPIの背後にある基盤は大きく成長する可能性があります。データが多すぎて、一度にすべてを取り戻すことができない場合があります。これにより、システムの速度が低下したり、システムが停止したりする可能性があります。したがって、アイテムをフィルタリングする方法が必要です。



また、一度に少数の結果のみを返すように、データをページ分割する方法（ページ分割）も必要です。要求されたすべてのデータを一度に取得しようとするリソースに時間がかかりすぎないようにします。



フィルタリングとデータページネーションはどちらも、サーバーリソースの使用を減らすことで、パフォーマンスを向上させることができます。データベースに蓄積されるデータが多いほど、これら2つの可能性が重要になります。



これは、APIがさまざまなパラメータを持つクエリ文字列を受け入れることができる小さな例です。フィールドでアイテムをフィルタリングしてみましょう。

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

//      
const employees = [
  { firstName: 'Jane', lastName: 'Smith', age: 20 },
  //...
  { firstName: 'John', lastName: 'Smith', age: 30 },
  { firstName: 'Mary', lastName: 'Green', age: 50 },
]

app.use(bodyParser.json());

app.get('/employees', (req, res) => {
  const { firstName, lastName, age } = req.query;
  let results = [...employees];
  if (firstName) {
    results = results.filter(r => r.firstName === firstName);
  }

  if (lastName) {
    results = results.filter(r => r.lastName === lastName);
  }

  if (age) {
    results = results.filter(r => +r.age === +age);
  }
  res.json(results);
});

app.listen(3000, () => console.log('server started'));

上記のコードには、req.queryリクエストパラメータを取得できる変数があります。次に、個々のクエリパラメータを変数に分解することで、プロパティ値を抽出できます。JavaScriptには、このための特別な構文があります。



最後に、各クエリパラメータ値にフィルタを適用して、返したいアイテムを見つけます。



これが完了すると、応答として結果が返されます。したがって、クエリ文字列を使用して次のパスにGET要求を行う場合：

/employees?lastName=Smith&age=30

我々が得る：

[
    {
        "firstName": "John",
        "lastName": "Smith",
        "age": 30
    }
]

フィルタリングがオンlastNameであったために返される応答としてage。



同様に、ページクエリパラメータを受け入れて、から(page - 1) * 20までの位置を占めるレコードのグループを返すことができますpage * 20。



また、クエリ文字列で、並べ替えを実行するフィールドを指定できます。この場合、これらの個別のフィールドで並べ替えることができます。たとえば、次のようなURLからクエリ文字列を抽出する必要がある場合があります。

http://example.com/articles?sort=+author,-datepublished

ここ+で、「上」と–「下」を意味します。そのため、著者名をアルファベット順に並べ替え、公開日を新しいものから古いものへと並べ替えます。

実績のあるセキュリティ慣行を順守する

機密情報を送受信することが多いため、クライアントとサーバー間の通信はほとんどプライベートにする必要があります。したがって、セキュリティにSSL / TLSを使用する必要があります。



SSL証明書をサーバーにアップロードするのはそれほど難しくなく、証明書自体は無料または非常に安価です。 REST APIがオープンチャネルではなく、安全なチャネルを介して通信できるようにすることを諦める理由はありません。



人は彼が要求したより多くの情報へのアクセスを与えられるべきではありません。たとえば、通常のユーザーは別のユーザーの情報にアクセスするべきではありません。また、管理者のデータを表示できないようにする必要があります。



最小特権の原則を推進するには、特定の役割の役割チェックを実装するか、各ユーザーに対してより詳細な役割を提供する必要があります。



ユーザーを複数のロールにグループ化する場合は、ユーザーが必要とするすべてのことを実行し、それ以上実行しないようにするアクセス権をロールに付与する必要があります。ユーザーに提供される各機会へのアクセス権をより詳細に規定する場合、管理者がこれらの機能をすべてのユーザーに付与できるようにするか、これらの機能を削除できるようにする必要があります。さらに、ユーザーグループに適用できる事前定義された役割をいくつか追加して、各ユーザーに必要な権限を手動で設定する必要がないようにする必要があります。

データをキャッシュしてパフォーマンスを向上させる

キャッシングを追加して、ユーザーが要求するたびにデータベースからデータを取得するのではなく、ローカルメモリキャッシュからデータを返すことができます。キャッシングの利点は、ユーザーがデータをより速く取得できることです。ただし、このデータは古くなっている可能性があります。これは、実稼働環境でデバッグするとき、問題が発生して古いデータを調べ続けるときにも問題が発生する可能性があります。Redis、メモリ内キャッシング



など、さまざまなキャッシングオプションを利用できます。必要に応じて、データのキャッシュ方法を変更できます。 たとえば、Expressはミドルウェアを提供します



apicache複雑な構成を行わずに、アプリケーションにキャッシュ機能を追加します。単純なメモリ内キャッシュは、次のようにサーバーに追加できます。

const express = require('express');

const bodyParser = require('body-parser');
const apicache = require('apicache');
const app = express();
let cache = apicache.middleware;
app.use(cache('5 minutes'));

//      
const employees = [
  { firstName: 'Jane', lastName: 'Smith', age: 20 },
  //...
  { firstName: 'John', lastName: 'Smith', age: 30 },
  { firstName: 'Mary', lastName: 'Green', age: 50 },
]

app.use(bodyParser.json());

app.get('/employees', (req, res) => {
  res.json(employees);
});

app.listen(3000, () => console.log('server started'));

上記のコードは単にapicachewithを参照しているためapicache.middleware、次のようになります。

app.use(cache('5 minutes'))

アプリケーション全体のキャッシングを適用するには、これで十分です。たとえば、すべての結果を5分でキャッシュします。その後、この値は必要に応じて調整できます。

APIバージョン管理

クライアントを混乱させる可能性のある変更を加えた場合に備えて、APIのバージョンを変える必要があります。バージョン管理はセマンティックベースで実行できます（たとえば、2.0.6はメジャーバージョンが2であることを意味し、これは6番目のパッチです）。この原則は現在、ほとんどのアプリケーションで受け入れられています。



このようにして、全員が同時に新しいAPIに切り替える必要がなく、古いエンドポイントを徐々に廃止できます。何も変更したくない人のためにv1バージョンを保存し、アップグレードの準備ができている人のためにv2バージョンにすべての新機能を提供することができます。これは、パブリックAPIのコンテキストで特に重要です。 APIを使用するサードパーティのアプリケーションが破損しないように、バージョン管理する必要があります。



バージョン管理は通常、を追加して行われます/v1/。/v2/、など、APIパスの先頭に追加されます。



たとえば、Expressでそれを行う方法は次のとおりです。

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());

app.get('/v1/employees', (req, res) => {
  const employees = [];
  //      
  res.json(employees);
});

app.get('/v2/employees', (req, res) => {
  const employees = [];
  //       
  res.json(employees);
});

app.listen(3000, () => console.log('server started'));

エンドポイントにつながるパスの先頭にバージョン番号を追加するだけです。

結論

高品質のRESTAPIを設計する際の重要なポイントは、Webの標準と規則に従うことで一貫性を維持することです。JSON、SSL / TLS、およびHTTPステータスコードは、今日のWebになくてはならないものです。



パフォーマンスも同様に重要です。一度に多くのデータを返さずに増やすことができます。さらに、キャッシングを使用して、同じデータを何度も要求することを回避できます。



エンドポイントパスには一貫した名前を付ける必要があります。HTTPメソッドの名前には動詞が含まれているため、名前には名詞を使用する必要があります。ネストされたリソースパスは、親リソースパスに従う必要があります。何が起こっているのかを理解するためにドキュメントをさらに参照する必要がないように、彼らは私たちが受け取ったり操作したりするものを伝える必要があります。