Scripted REST APIs の推奨プラクティス

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：4分

    • Scripted REST APIs を設計および実装するときは、次のガイドラインに従ってください。

    REST API の規則に従う

    REST API 標準を使用して、一貫性のある使いやすいインターフェイスをクライアントに提供します。REST API の規則はメソッドのタイプごとに特定の動作を定義します。API を設計する際の開始点として、次のガイドラインを使用してください。

    • GET 操作はデータのクエリのみを行います。GET 要求でデータを変更することはできません。
    • POST の操作では新しいレコードが作成されますが、既存のレコードは変更されません。
    • PUT および PATCH の操作は既存のレコードを変更します。
    • DELETE の操作ではレコードが破棄されます。

    バージョニングを使用して API の変更を制御する

    バージョニングを使用して新しい機能を実装し、既存の統合を中断しないようにします。API の機能を大幅に変更する場合は、まず API の新しいバージョンを作成します。公開されたバージョンで既存の統合を中断する動作を導入しないでください。

    バージョニングを使用すると、既存のクライアントを中断することなく API に大幅な変更を実装できます。その後、既存のクライアントが自分のペースでアップグレードできるようにすると同時に、新しいクライアント用に新しいバージョンの API をリリースできます。

    バージョン固有の API を使用するようにクライアントに勧めるか、デフォルトのバージョンを指定せずに API を構成して、クライアントにバージョンの指定を強制します。既存のバージョンにオプションのパラメーターを追加することで、新しいオプションの動作を利用可能にすることもできます。

    有益な HTTP ステータスコードを返す

    要求の成功または失敗を要求者に通知するステータスコードを返します。クライアントが要求の結果を理解するのに役立つ HTTP ステータスコードを返します。一般的なステータスコードについては、次のガイドラインを使用してください。

    表 : 1. 一般的なステータスコード
    ステータスコード 説明
    200 要求が正常に完了したことを示します。
    201 レコードが正常に作成されたことを示します。
    204 レコードが正常に削除されたことを示します。
    40X (401, 404) 400 の範囲のステータスコードは、無効な要求構文の 400 など、クライアントエラーを示します。
    50X (500, 503) 500 の範囲のステータスコードは、サーバーエラーが発生したことを示します。クライアント要求が有効または無効である可能性がありますが、サーバーで問題が発生し、要求を処理できませんでした。

    有用なエラー情報を返す

    クライアントが API ドキュメントを参照しなくても問題を理解できるように、エラーメッセージに十分な情報を提供してください。エラー応答には、役に立つエラーメッセージとエラーステータスコードを含める必要があります。

    たとえば、クライアントが存在しないレコードを照会すると、「指定されたレコードが存在しません。ID <id 値> のレコードがアプリケーションに存在します。(The specified record does not exist. Ensure that a record with the ID of <id value> exists in the application.)」というエラーメッセージが 404 ステータスコードとともに表示されます。

    Scripted REST API 機能には、よく発生するエラーに使用できる事前設定されたエラーオブジェクトと、事前設定されたエラーオブジェクトがニーズを満たしていない場合に使用できるカスタマイズ可能な ServiceRequest エラーオブジェクトが含まれています。

    アクセス制御を適用してテストする

    既存のアクセス制御を適用します。データを変更するには追加のアクセス権が必要です。API にアクセスするための認証に加えて、データにアクセスするための認証が必要です。Scripted REST API スクリプトで GlideRecordSecure API を使用します。この API は、基になるデータに対して定義されたアクセス制御が要求ユーザーに適用されるようにします。

    データを変更する操作には追加のアクセス制御が必要です。PUT、POST、および DELETE などの要求には、GET よりも高いレベルのアクセス権が必要です。より厳格な ACL を要求するようにこれらの API リソースを設定します。

    API をリリースする前に、認証と認可の両方のアクセス制御をテストします。

    機能を検証するテストを構築する

    開発プロセスの一部として、スクリプト化された REST Web サービスの機能を検証するテストを構築します。反復可能なテストを使用して、API が想定どおりに機能することを確認します。テストは、行った変更がバージョンのリリース後に予想される API の動作に影響しないことを確認するのにも役立ちます。Postman などの自動テストをサポートする REST クライアントアプリケーションを使用して、テストを容易にすることができます。

    テストでは、実装するリソースごとに応答コード、ヘッダー、および本文の内容を検証する必要があります。テストを使用して認証要件を検証し、エラーが有用な応答を返すことを確認することもできます。