Including related entities

CSPR.cloud REST API provides the possibility to include related entities in responses. An entity is called related if its identifier is present among the requested entity's properties. For example, the Deploy entity is related to the NFT Action entity because the latter has a deploy_hash property identifying the deploy that produced the action. Not all related entities can be included in responses; the ones that can are listed in the "Optional properties" section for the corresponding entity or endpoint page.

Related entities are included the same as other optional properties, using the includes query param. For the related entity to be added to the response, its name has to be specified in the list of includes.

Including related entities makes it possible to fetch the required data in one request, simplifying the integration and reducing latency, which is especially useful when processing paginated responses. Continuing the NFT Action and Deploy example, one may need to know the deploy caller account when processing the NFT Action data. By including the Deploy object in the NFT Action response, all the required information can be received in just one API call instead of requesting the deploy data for each NFT action in the list:

curl -X 'GET' \
  'https://api.testnet.cspr.cloud/contract-packages/998af6825d77da15485baf4bb89aeef3f1dfb4a78841d149574b0be694ce4821/nft-tokens/2/actions?includes=deploy' \
  -H 'accept: application/json' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a'

{
  "data": [
    {
      "contract_package_hash": "998af6825d77da15485baf4bb89aeef3f1dfb4a78841d149574b0be694ce4821",
      "deploy": {
        "args": {
          "recipient": {
            "cl_type": "Key",
            "parsed": {
              "Account": "account-hash-989ca079a5e446071866331468ab949483162588d57ec13ba6bb051f1e15f8b7"
            }
          },
          "token_ids": {
            "cl_type": {
              "List": "U256"
            },
            "parsed": [
              "2"
            ]
          }
        },
        "block_hash": "6dd2def46e2417f05dbbb3b8429099f20f89f7fb4b32d4e61fd5d79959ba35f8",
        "caller_public_key": "013eecc2f0fbcad01a35fca7ad0bf191a8cf1eb8d6b13ea63cb92a31e6c767c0bc",
        "contract_hash": "ff2f649f127c033d744f80e7c3bcf0561c716d8f6d1dadc0cd79d8b2d309c020",
        "contract_package_hash": "998af6825d77da15485baf4bb89aeef3f1dfb4a78841d149574b0be694ce4821",
        "cost": "801777450",
        "deploy_hash": "7ffa747cf92deace24a8f81f62ed01694271940ac16e20c419a56f47f680f0a5",
        "entry_point_id": 96622,
        "error_message": null,
        "execution_type_id": 4,
        "payment_amount": "1000000000",
        "status": "processed",
        "timestamp": "2022-10-28T13:40:14Z"
      },
      "deploy_hash": "7ffa747cf92deace24a8f81f62ed01694271940ac16e20c419a56f47f680f0a5",
      "from_hash": "c1e4f35cf36553d9acca0fa02be97537f333c18783373e34d6932eb649584a8c",
      "from_type": 0,
      "nft_action_id": 4,
      "timestamp": "2022-10-28T13:40:14Z",
      "to_hash": "989ca079a5e446071866331468ab949483162588d57ec13ba6bb051f1e15f8b7",
      "to_type": 0,
      "token_id": "2",
      "token_tracking_id": 20709
    },
    {
      "contract_package_hash": "998af6825d77da15485baf4bb89aeef3f1dfb4a78841d149574b0be694ce4821",
      "deploy": {
        "args": {
          "token_meta_data": {
            "cl_type": "String",
            "parsed": "{\"token_uri\":\"ipfs://\"}"
          },
          "token_owner": {
            "cl_type": "Key",
            "parsed": {
              "Account": "account-hash-d0bc9ca1353597c4004b8f881b397a89c1779004f5e547e04b57c2e7967c6269"
            }
          }
        },
        "block_hash": "928a4518bd001cc4ba07a6405e2a2053c157a8a16f0df08668a8aa4d12b7ddbf",
        "caller_public_key": "016d9e3db0a800aef8d18975b469c77bef042ee909d24cb83d27df97a22bb6d8ad",
        "contract_hash": "4a2c7bda207ddf20487c13bd882a0773e1047c0544024bfae4a40e8769a8f452",
        "contract_package_hash": "e2e9be86fb0bef6f2df08c0e3b49cc66ce458a40e496e115f6dc984011177d16",
        "cost": "6398252230",
        "deploy_hash": "af1d08519310188c9746f090d7a0d999da13b58d64680086277bdecebfd29628",
        "entry_point_id": 117617,
        "error_message": null,
        "execution_type_id": 2,
        "payment_amount": "10381644690",
        "status": "processed",
        "timestamp": "2023-01-01T09:40:04Z"
      },
      "deploy_hash": "af1d08519310188c9746f090d7a0d999da13b58d64680086277bdecebfd29628",
      "from_hash": null,
      "from_type": null,
      "nft_action_id": 1,
      "timestamp": "2023-01-01T09:40:04Z",
      "to_hash": "d0bc9ca1353597c4004b8f881b397a89c1779004f5e547e04b57c2e7967c6269",
      "to_type": 0,
      "token_id": "2",
      "token_tracking_id": 20709
    }
  ],
  "item_count": 2,
  "page_count": 1
}