---
sourceDocument: Xanadu API リファレンス
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - ja-JP

ft:publication_title :

    - Xanadu API リファレンス

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

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

# Scripted REST APIs の推奨プラクティス {#ariaid-title1}

* リリースバージョン: Xanadu
* 
* 更新日 2024年08月01日
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：4分

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

## REST API の規則に従う {#scripted-rest-good-practices__section_xwf_flr_23b}

REST API 標準を使用して、一貫性のある使いやすいインターフェイスをクライアントに提供します。REST API の規則はメソッドのタイプごとに特定の動作を定義します。API を設計する際の開始点として、次のガイドラインを使用してください。  
* GET 操作はデータのクエリのみを行います。GET 要求でデータを変更することはできません。
* POST の操作では新しいレコードが作成されますが、既存のレコードは変更されません。
* PUT および PATCH の操作は既存のレコードを変更します。
* DELETE の操作ではレコードが破棄されます。
{#scripted-rest-good-practices__ul_tbd_3lr_23b}

## バージョニングを使用して API の変更を制御する {#scripted-rest-good-practices__section_km4_mlr_23b}

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

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

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

## 有益な HTTP ステータスコードを返す {#scripted-rest-good-practices__section_xbn_qlr_23b}

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

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

{#scripted-rest-good-practices__table_cbv_2rh_dw}

## 有用なエラー情報を返す {#scripted-rest-good-practices__section_gwd_vlr_23b}

クライアントが 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 エラーオブジェクトが含まれています。

## アクセス制御を適用してテストする {#scripted-rest-good-practices__section_efh_1mr_23b}

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

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

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

## 機能を検証するテストを構築する {#scripted-rest-good-practices__section_hlf_hmr_23b}

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

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