---
sourceDocument: オーストラリア API リファレンス
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/api-reference

 Release :

    - australia

ft:locale :

    - ja-JP

ft:publication_title :

    - オーストラリア API リファレンス

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

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

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

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

{#scripted-rest-good-practices__table_cbv_2rh_dw}

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

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

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

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

## アクセス制御の適用とテスト {#scripted-rest-good-practices__section_efh_1mr_23b}

既存のアクセス制御を適用し、データを変更するには追加のアクセス権を要求します。API へのアクセスに認証を要求することに加えて、データへのアクセスにも認証を要求します。スクリプト化された 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 クライアントアプリケーションを使用して、テストを容易にすることができます。

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