基本応答のペイロード構造

基本的な応答の高度な構造は、以下に示すとおりです。最初と最後のプロパティ（count とコレクションレベルの links）は、コレクションペイロードでのみ使用されます。その他すべてのプロパティは、要素ペイロードとコレクションペイロードの両方で使用されます。

（注意：JSON ではコメントをサポートしません。ただし、コードを明確化するため、擬似コメントが追加されています。各擬似コメントの前にはハッシュタグ（#）が付きます。）

{
      "count": N,                      # Number of resources in collection*
      "data": [                        # List of resources
          {                            # Resource 1 begins here
          "attributes": {              # Resource 1 name/value pairs
              "propertyName": "propertyValue",
              ... },
          "checksum": "val",           # Resource 1 checksum value
          "links": { ... }             # Resource 1 links 
          },                           # Resource 1 ends here
          {                            # Resource 2 begins here
          "attributes": {              # Resource 2 name/value pairs
              "propertyName": "propertyValue",
              ... },
          "checksum": "val",           # Resource 2 checksum value
          "links": { ... }             # Resource 2 links 
          },                           # Resource 2 ends here
      ... ],                           # Resources 3 to N
      "links": { ... }                 # Collection-level links*
}
                                       # *-used only for collection responses

count プロパティは、ペイロードで返される要素の数を特定します。コレクションを含む応答でのみ使用されます。

data セクションには、エンドポイントが返すリソースについての情報が含まれます。各リソースについて、以下のサブセクションがデフォルトで表示されます。

• attributes：各リソースのフィールドにおける名前／値ペアのセット
• checksum：各リソースのチェックサム値
• links：各応答でアクションの実行に使用できる HTTP リンク

エンドポイントが単一要素を返す場合、data セクションには attributes、checksum、および links の単一セットが含まれます。エンドポイントがコレクションを返す場合、data セクションには、各リソースの attributes、checksum、および links が 1 セットずつ含まれます。

attributes サブセクションに一覧表示される内容は、リソースに返されるフィールドとそのフィールドの値です。例：

"attributes": {
    "activityPattern": "check_coverage",
    "activityType": {
        "code": "general",
        "name": "General"
    },
    ...
},

各リソースには、返されるフィールドのデフォルトセットがあります。これは通常、返すことができるすべてのフィールドのサブセットです。fields クエリパラメータを使用して、返されるフィールドのデフォルトセットを上書きできます。詳細については、GET を行うフィールドの指定を参照してください。

"subject": "Verify which coverage is appropriate"

"id": "xc:20",

GET /activities/xc:20/notes

"inlinedResourceName": {
    "inlinedResourceField1": value,
    "inlinedResourceField2": value,
    ...
},

"priority": {
    "code": "urgent",
    "name": "Urgent"
},

"transactionAmount": {
    "amount": "500.00",
    "currency": "usd"

"assignedGroup": {
    "displayName": "Auto1 - TeamA",
    "id": "demo_sample:31"
},
"assignedUser": {
    "displayName": "Andy Applegate",
    "id": "demo_sample:1"
},

checksum フィールドには、リソースの「バージョン」を特定する値が一覧表示されます。リソースがデータベースレベルで変更される場合は必ず、新しいチェックサム値が割り当てられます。データ変更のプロセスでは、チェックサムを使用して、リソースで読み取りが行われた時刻と変更が行われた時刻との間に、他のプロセスによって変更が行われていないことを確認できます。

詳細については、ロストアップデートとチェックサムを参照してください。

特定の要素に対して実行できるアクションを特定するパスのセットがあれば、data セクションの links サブセクションで、一覧表示します。各リンクには名前、href プロパティ、およびメソッドのリストがあります。呼び出し元アプリケーションはこれらのリンクを使用して、そのリソースに対して実行する追加アクションの HTTP 要求を作成できます。

例えば、ある呼び出し元アプリケーションがアクティビティ xc:20 を取得するとします。このアプリケーションに付与されている権限により、このアクティビティをアサインして、アクティビティに関連付けられた備考・経緯を表示できます。アクティビティ xc:20 の links セクションには以下の内容が表示されます。

"links": {
    "assign": {
        "href": "/common/v1/activities/xc:20/assign",
        "methods": [
            "post"
        ]

    },
    "notes": {
        "href": "/common/v1/activities/xc:20/notes",
        "methods": [
            "get",
            "post"
        ]
    },
    "self": {
        "href": "/common/v1/activities/xc:20",
        "methods": [
            "get"
        ]
    }
}

self リンクは、リソースそのものへのリンクです。self リンクが有用な場合は、呼び出し元アプリケーションがリソースのリストを受信してリストで特定リソースへのナビゲーションを行う場合です。

特定のオブジェクトに対して、ビジネスアクションを実行するリンクが表示される場合は、一定のオブジェクト状態が前提となるアクションが適切な場合のみと、アクションの実行に十分な権限が呼び出し元にある場合のみです。例えば、アクティビティをクローズするリンクは、アクティビティがクローズされている場合に表示されません。同様に、アクティビティをアサインするリンクは、アクティビティのアサインに必要な権限が呼び出し元にない場合は表示されません。

応答にコレクションが含まれる場合、ペイロードの末尾に links セクションが含まれます。このセクションは、data セクションと兄弟関係にあります。大規模なリソースセットでページをめくるように移動するために、prev リンクや next リンクなど、コレクション全体に関連するリンクが含まれます。