Qumuloでのエンジニアリング：REST API

2016 年 5 月 6 日

作成者：

クムロチーム

ファイルシステムの構築を最初に開始したとき、コマンドラインツール、UI、および自動テストを使用してファイルシステムを制御および検査できるようにしたいと考えていました。を使って REST API この機能を公開するのは当然のことであり、Qumulo内でこの機能が必要な場合は、お客様も必要になる可能性があることに気付きました。そのため、最初からRESTAPIを公開することにしました。

この投稿では、APIの信条、RESTの課題、およびファイルシステムとともにAPIを継続的に進化させる方法について説明します。

RESTAPIの教義

Representational State Transfer（REST）は、広く使用されているアーキテクチャスタイルであり、既にご存知の方もいらっしゃると思います。 RESTを使用して新しいAPIを定義する際には、途中で多くの選択肢があります。まず、APIにどのような機能を組み込むかを決定する必要があります。コントロールプレーン（システム構成と統計）？データプレーン（ファイルシステムに保存されているファイルとメタデータ）？機能開発を支援するために、両方に加えて、内部のみのエンドポイントを選択しました。 Qumuloクラスターで実行できることはすべて、RESTAPIを介して実行できます。

次に、回答内容について検討しました。 SMBやNFSなどのファイルシステムプロトコルを使用してメタデータを読み取る場合、そのプロトコルによるファイルシステムの状態の解釈が得られ、表現できる内容が制限される可能性があります。対照的に、REST APIはグラウンドトゥルースを返します。クライアントは返されたデータを解釈する必要がなく、利用可能なすべての情報を返します。ファイルシステムの機能を拡張すると（集約されたメタデータの保存など）、エンドポイントを拡張してこれらの機能を公開します。

REST APIデザインルールブックに触発されて、各エンドポイントを次のリソースアーキタイプのXNUMXつとして分類します。

ドキュメント：フィールドと関連リソースへのリンクの両方を含むデータベースレコード
収集：リソースのディレクトリ（通常はドキュメントリソース）
コントローラー：実行可能関数（「メール送信」など）
オンラインショップ：クライアント管理のリソースリポジトリ（通常、APIでは使用されません）

URIを構造化する際に、開発者や管理者がエンドポイントに対してスクリプトを作成したり、cURLなどのツールを使用したりするのを簡単にしたいと考えました。また、エンドポイントの契約が変更された場合にクライアントが誤って破損しないようにする必要もありました。これにより、バージョン番号など、より多くのコンテンツをURIに配置し、暗黙的なコントラクトよりも明示的なコントラクトを優先するようになりました。たとえば、ディレクトリを読み取る方法は次のとおりです。

/ v1	/ files /	％2F	/ entries /	？limit = 1000

/ v1：エンドポイントのバージョンが常に最初に来る
/ files /：アクセスするドキュメント、コレクション、またはコントローラー。この場合、/ files /はコレクションです。
％2F：ファイルコレクション内のドキュメントのID。この場合、ファイルシステムのルートディレクトリ。
/ entries /：指定されたファイル/フォルダーに対して実行するアクション。
？limit = 1000：最後に、アクションへのオプションのクエリパラメータ。

この設計では、必要なHTTPヘッダーはOAuth2スタイルのベアラートークンの承認のみです。

curl -k -X GET -H "Authorization: Bearer <token>" https://server:8000/v1/file-system</var/www/wordpress>

既存のファイルシステム REST API を模倣しようとしたわけではないことは注目に値します。私たちは、API がファイルシステムの機能に特化し、ユーザーがシステムを最大限に制御できるようにしたいと考えていました。将来のある時点で、S3、WebDAV、またはその他を通信するクライアントをサポートしたい場合は、それらのプロトコル用の新しいポートを追加し、コア REST API から分離する予定です。

REST に関する課題

構成エンドポイントの多くは単純な動作をします。 GET</var/www/wordpress> to retrieve a document (e.g. GET /v1/users/123</var/www/wordpress>), and you use SET</var/www/wordpress> or PATCH</var/www/wordpress> to update the document. The requests take effect immediately, so that when you receive a 200 OK</var/www/wordpress> response, you know the change has been made.

ただし、REST はステートフルでもトランザクションでもないため、適切に考慮しないとユーザーエクスペリエンスに影響を与える可能性があります。管理者が組み込み UI を使用してクラスター上のファイル共有を編集しているとします。 UI がファイル共有の詳細を取得してから、管理者が変更を保存するまでの間に、別のユーザーまたはプロセスがそのファイル共有を変更する可能性があります。 API のデフォルトでは、最後の作成者が優先されるため、管理者はこれらの変更を無意識に破壊してしまいます。それは私たちが望むユーザーエクスペリエンスではないので、 ETag</var/www/wordpress> and If-Match</var/www/wordpress> HTTP headers for all of our documents to prevent accidental overwrites. When the UI retrieves a document, it reads the ETag</var/www/wordpress> response header (entity tag, or essentially a hashcode) and stores that. Later, when updating that same document, the UI sends an If-Match</var/www/wordpress> request header, which tells the cluster to only perform the action if the document is the same as we expect. If the document changed, we’ll get back a 12 Precondition Failed</var/www/wordpress> response, which allows us to build a better experience for the user.

長時間実行されるアクションにも特別な考慮が必要です。 REST API の応答時間を予測可能に保つために、実行時間の短いリクエストは同期的に処理し、実行時間の長いリクエストは非同期的に処理します。 API 内のすべてのエンドポイントを短期実行または長期実行として分類し、複雑さを軽減するためにクライアントがどのような種類の応答を処理する必要があるかを把握できるようにします。全て GET, PUT</var/www/wordpress>, and PATCH</var/www/wordpress> operations on documents and collections are short-running requests, returning 200 OK</var/www/wordpress> when successfully processed. In contrast, we always POST to a controller endpoint for long-running requests, which return 202 Accepted</var/www/wordpress> with a URI to poll for completion status. For example, when joining a cluster to Active Directory, the client invokes the controller like this:

リクエスト	POST /v1/ad/join
ボディをリクエストする	{ 「ドメイン」: 「ad.server.com」、「ユーザー」: 「ドメインユーザー」、「パスワード」: 「ドメインパスワード」、 ... }

リクエストが有効な場合、コントローラーは次のように応答します。

リクエスト	POST /v1/ad/join
202受け入れ	{ 「monitor_uri」: 「/v1/ad/monitor」 }

その後、クライアントは繰り返し発行することができます GET /v1/ad/monitor</var/www/wordpress> calls while waiting for the join action to succeed or fail.

REST APIの進化

REST API がファイルシステムの機能に確実に対応できるようにするために、エンドポイントはコードから自動生成されます。これは、ファイルシステム、API、および API ドキュメントが常に同期されていることを意味します。当社のビルドシステムは、API クライアントを破壊する REST API の変更をもたらす内部データ構造への誤った変更を防止します。また、API ドキュメントをコードに組み込むことで、コードを最新の状態に保つことができます。

REST API の開発から XNUMX 年後、私たちは問題があることに気づきました。さまざまな開発チームが機能を追加するにつれて API が有機的に成長し、その結果、エンドポイント間で不一致が発生し、機能の発見が困難になる疑わしい階層が発生しました。これに対処するために、私たちは XNUMX つのことを行いました。一貫性と発見可能性の問題を修正するために一連のリリースにわたって新しい API 名前空間に移行しました。もう XNUMX つは、API の進化と一貫性の維持を可能にする Qumulo エンジニアが従う API ロードマップを作成しました。 API 名前空間の改善の例としては、すべての API 名前空間の統合が挙げられます。リアルタイム分析/v1/analytics に関連する機能。以前は、この機能は名前空間全体に分散していましたが、これらの機能が見つからないというお客様の声を聞いて、これが改善の余地があると認識しました。

/v1 API を強化したので、重大な変更が必要な場合は、個々のエンドポイントのバージョンを変更できます。 (重大な変更には、リクエストへの新しい必須フィールドの追加や、返されるデータのセマンティクスの変更などが含まれます。)この規定があっても、重大な変更は最後の手段です。私たちは、既存の API クライアントに影響を与えることなく、応答データを強化したり、オプションのフィールドを導入したりする方法を見つけるよう努めています。

この投稿では、Qumulo の REST API の理念、REST のいくつかの課題にどのように取り組んだか、製品と連携して API を進化させるためのアプローチについて説明しました。