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

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：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 レコードが正常に削除されたことを示します。
    40倍 (401、404) 400 の範囲のステータスコードは、クライアントエラーを示します。たとえば、無効な要求構文の場合は 400 です。
    50倍 (500、503) 500 の範囲のステータスコードは、サーバーエラーが発生したことを示します。クライアント要求が有効であるか無効である可能性がありますが、サーバーで問題が発生し、要求を処理できませんでした。

    有用なエラー情報を返します

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

    たとえば、クライアントが存在しないレコードをクエリーすると、エラーメッセージ「指定されたレコードは存在しません。ID が <id 値> のレコードがアプリケーションに存在することを確認します。」と 404 ステータスコードが表示されます。

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

    アクセス制御の適用とテスト

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

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

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

    機能を確認するためのビルドテスト

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

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