Fetching multiple associated resources

Vendo APIs allow you to fetch multiple associated resources in one API call, both for singular resources and collections, eg. we can fetch a Product with all of its variants and images:

curl --request GET \
     --url 'https://demo.getvendo.com/api/v2/storefront/products/classic-varsity-top?include=variants%252Cimages' \
     --header 'Accept: application/vnd.api+json'

This will return a JSON response:

{
  "data": {
    "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
    "type": "product",
    "attributes": {
      "name": "Classic Varsity Top",
      "description": "<p>Womens casual varsity top, This grey and black buttoned top is a sport-inspired piece complete with an embroidered letter.</p>",
      "available_on": "2022-02-16T00:00:00.000-06:00",
      "slug": "classic-varsity-top",
      "meta_description": "",
      "meta_keywords": "",
      "updated_at": "2022-03-09T10:04:21.407-06:00",
      "sku": "",
      "barcode": null,
      "public_metadata": {},
      "purchasable": true,
      "in_stock": true,
      "backorderable": true,
      "available": false,
      "currency": "USD",
      "price": "60.0",
      "display_price": "$60.00",
      "compare_at_price": null,
      "display_compare_at_price": null
    },
    "relationships": {
      "variants": {
        "data": [
          {
            "id": "15c2c274-47b2-4d16-ac76-acd43f3cae6d",
            "type": "variant"
          },
          {
            "id": "17054e7c-d224-425f-ab5a-0fd88443bd51",
            "type": "variant"
          },
          {
            "id": "13fd26cd-0f16-4a52-aa51-88b5a4f01462",
            "type": "variant"
          }
        ]
      },
      "option_types": {
        "data": [
          {
            "id": "143b3650-0f2f-49d2-8514-9efa52bc8cf0",
            "type": "option_type"
          }
        ]
      },
      "product_properties": {
        "data": []
      },
      "taxons": {
        "data": []
      },
      "images": {
        "data": [
          {
            "id": "0852d81d-df7c-4165-af42-2d5bb4d45014",
            "type": "image"
          }
        ]
      },
      "default_variant": {
        "data": {
          "id": "15c2c274-47b2-4d16-ac76-acd43f3cae6d",
          "type": "variant"
        }
      },
      "primary_variant": {
        "data": {
          "id": "6504bea4-92aa-4899-8a5a-055eb448d4e9",
          "type": "variant"
        }
      },
      "vendor": {
        "data": {
          "id": "51c35adb-7ab3-4880-8887-35bdc4f6c29f",
          "type": "vendor"
        }
      }
    }
  },
  "included": [
    {
      "id": "15c2c274-47b2-4d16-ac76-acd43f3cae6d",
      "type": "variant",
      "attributes": {
        "sku": "classic-varsity-top-small",
        "barcode": null,
        "weight": "0.0",
        "height": null,
        "width": null,
        "depth": null,
        "is_master": false,
        "options_text": "Size: Small",
        "public_metadata": {},
        "purchasable": true,
        "in_stock": true,
        "backorderable": true,
        "currency": "USD",
        "price": "60.0",
        "display_price": "$60.00",
        "compare_at_price": null,
        "display_compare_at_price": null
      },
      "relationships": {
        "product": {
          "data": {
            "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
            "type": "product"
          }
        },
        "images": {
          "data": []
        },
        "option_values": {
          "data": [
            {
              "id": "111369fc-17bd-4326-a7c5-13cff4c9f643",
              "type": "option_value"
            }
          ]
        }
      }
    },
    {
      "id": "17054e7c-d224-425f-ab5a-0fd88443bd51",
      "type": "variant",
      "attributes": {
        "sku": "classic-varsity-top-medium",
        "barcode": null,
        "weight": "0.0",
        "height": null,
        "width": null,
        "depth": null,
        "is_master": false,
        "options_text": "Size: Medium",
        "public_metadata": {},
        "purchasable": true,
        "in_stock": true,
        "backorderable": true,
        "currency": "USD",
        "price": "60.0",
        "display_price": "$60.00",
        "compare_at_price": null,
        "display_compare_at_price": null
      },
      "relationships": {
        "product": {
          "data": {
            "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
            "type": "product"
          }
        },
        "images": {
          "data": []
        },
        "option_values": {
          "data": [
            {
              "id": "69485fa2-3fc3-4d12-9b25-af2cbe2ac0bd",
              "type": "option_value"
            }
          ]
        }
      }
    },
    {
      "id": "13fd26cd-0f16-4a52-aa51-88b5a4f01462",
      "type": "variant",
      "attributes": {
        "sku": "classic-varsity-top-large",
        "barcode": null,
        "weight": "0.0",
        "height": null,
        "width": null,
        "depth": null,
        "is_master": false,
        "options_text": "Size: Large",
        "public_metadata": {},
        "purchasable": true,
        "in_stock": true,
        "backorderable": true,
        "currency": "USD",
        "price": "60.0",
        "display_price": "$60.00",
        "compare_at_price": null,
        "display_compare_at_price": null
      },
      "relationships": {
        "product": {
          "data": {
            "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
            "type": "product"
          }
        },
        "images": {
          "data": []
        },
        "option_values": {
          "data": [
            {
              "id": "b7838bbb-e498-4971-9dfa-de9f1b19cc28",
              "type": "option_value"
            }
          ]
        }
      }
    },
    {
      "id": "0852d81d-df7c-4165-af42-2d5bb4d45014",
      "type": "image",
      "attributes": {
        "transformed_url": null,
        "styles": [
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_48,w_48/grpelxqjwccqhmxaxagx",
            "size": "48x48>",
            "width": 48,
            "height": 48
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_100,w_100/grpelxqjwccqhmxaxagx",
            "size": "100x100>",
            "width": 100,
            "height": 100
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_240,w_240/grpelxqjwccqhmxaxagx",
            "size": "240x240>",
            "width": 240,
            "height": 240
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_200,w_160/grpelxqjwccqhmxaxagx",
            "size": "160x200>",
            "width": 160,
            "height": 200
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_600,w_448/grpelxqjwccqhmxaxagx",
            "size": "448x600>",
            "width": 448,
            "height": 600
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_340,w_254/grpelxqjwccqhmxaxagx",
            "size": "254x340>",
            "width": 254,
            "height": 340
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_468,w_350/grpelxqjwccqhmxaxagx",
            "size": "350x468>",
            "width": 350,
            "height": 468
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_297,w_222/grpelxqjwccqhmxaxagx",
            "size": "222x297>",
            "width": 222,
            "height": 297
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_371,w_278/grpelxqjwccqhmxaxagx",
            "size": "278x371>",
            "width": 278,
            "height": 371
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_600,w_600/grpelxqjwccqhmxaxagx",
            "size": "600x600>",
            "width": 600,
            "height": 600
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_371,w_278/grpelxqjwccqhmxaxagx",
            "size": "278x371>",
            "width": 278,
            "height": 371
          },
          {
            "url": "https://res-1.cloudinary.com/vendo-production/image/upload/b_rgb:ffffff,c_thumb,h_870,w_650/grpelxqjwccqhmxaxagx",
            "size": "650x870>",
            "width": 650,
            "height": 870
          }
        ],
        "position": 1,
        "alt": null,
        "original_url": "https://res-1.cloudinary.com/vendo-production/image/upload/grpelxqjwccqhmxaxagx",
        "attachment_width": 925,
        "attachment_height": 617,
        "attachment_content_type": "image/jpg"
      }
    }
  ]
}

Notice the data[relationships] (links to what resources connects to which) node and included (images and variants JSON responses).

Nested resources

You can also nest this, eg. fetching Product Variants with their Option Values:

curl --request GET \
     --url 'https://demo.getvendo.com/api/v2/storefront/products/classic-varsity-top?include=variants.option_values' \
     --header 'Accept: application/vnd.api+json'

This will return JSON:

{
  "data": {
    "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
    "type": "product",
    "attributes": {
      "name": "Classic Varsity Top",
      "description": "<p>Womens casual varsity top, This grey and black buttoned top is a sport-inspired piece complete with an embroidered letter.</p>",
      "available_on": "2022-02-16T00:00:00.000-06:00",
      "slug": "classic-varsity-top",
      "meta_description": "",
      "meta_keywords": "",
      "updated_at": "2022-03-09T10:04:21.407-06:00",
      "sku": "",
      "barcode": null,
      "public_metadata": {},
      "purchasable": true,
      "in_stock": true,
      "backorderable": true,
      "available": false,
      "currency": "USD",
      "price": "60.0",
      "display_price": "$60.00",
      "compare_at_price": null,
      "display_compare_at_price": null
    },
    "relationships": {
      "variants": {
        "data": [
          {
            "id": "15c2c274-47b2-4d16-ac76-acd43f3cae6d",
            "type": "variant"
          },
          {
            "id": "17054e7c-d224-425f-ab5a-0fd88443bd51",
            "type": "variant"
          },
          {
            "id": "13fd26cd-0f16-4a52-aa51-88b5a4f01462",
            "type": "variant"
          }
        ]
      },
      "option_types": {
        "data": [
          {
            "id": "143b3650-0f2f-49d2-8514-9efa52bc8cf0",
            "type": "option_type"
          }
        ]
      },
      "product_properties": {
        "data": []
      },
      "taxons": {
        "data": []
      },
      "images": {
        "data": [
          {
            "id": "0852d81d-df7c-4165-af42-2d5bb4d45014",
            "type": "image"
          }
        ]
      },
      "default_variant": {
        "data": {
          "id": "15c2c274-47b2-4d16-ac76-acd43f3cae6d",
          "type": "variant"
        }
      },
      "primary_variant": {
        "data": {
          "id": "6504bea4-92aa-4899-8a5a-055eb448d4e9",
          "type": "variant"
        }
      },
      "vendor": {
        "data": {
          "id": "51c35adb-7ab3-4880-8887-35bdc4f6c29f",
          "type": "vendor"
        }
      }
    }
  },
  "included": [
    {
      "id": "111369fc-17bd-4326-a7c5-13cff4c9f643",
      "type": "option_value",
      "attributes": {
        "name": "Small",
        "presentation": "Small",
        "position": 1,
        "public_metadata": {}
      },
      "relationships": {
        "option_type": {
          "data": {
            "id": "143b3650-0f2f-49d2-8514-9efa52bc8cf0",
            "type": "option_type"
          }
        }
      }
    },
    {
      "id": "15c2c274-47b2-4d16-ac76-acd43f3cae6d",
      "type": "variant",
      "attributes": {
        "sku": "classic-varsity-top-small",
        "barcode": null,
        "weight": "0.0",
        "height": null,
        "width": null,
        "depth": null,
        "is_master": false,
        "options_text": "Size: Small",
        "public_metadata": {},
        "purchasable": true,
        "in_stock": true,
        "backorderable": true,
        "currency": "USD",
        "price": "60.0",
        "display_price": "$60.00",
        "compare_at_price": null,
        "display_compare_at_price": null
      },
      "relationships": {
        "product": {
          "data": {
            "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
            "type": "product"
          }
        },
        "images": {
          "data": []
        },
        "option_values": {
          "data": [
            {
              "id": "111369fc-17bd-4326-a7c5-13cff4c9f643",
              "type": "option_value"
            }
          ]
        }
      }
    },
    {
      "id": "69485fa2-3fc3-4d12-9b25-af2cbe2ac0bd",
      "type": "option_value",
      "attributes": {
        "name": "Medium",
        "presentation": "Medium",
        "position": 2,
        "public_metadata": {}
      },
      "relationships": {
        "option_type": {
          "data": {
            "id": "143b3650-0f2f-49d2-8514-9efa52bc8cf0",
            "type": "option_type"
          }
        }
      }
    },
    {
      "id": "17054e7c-d224-425f-ab5a-0fd88443bd51",
      "type": "variant",
      "attributes": {
        "sku": "classic-varsity-top-medium",
        "barcode": null,
        "weight": "0.0",
        "height": null,
        "width": null,
        "depth": null,
        "is_master": false,
        "options_text": "Size: Medium",
        "public_metadata": {},
        "purchasable": true,
        "in_stock": true,
        "backorderable": true,
        "currency": "USD",
        "price": "60.0",
        "display_price": "$60.00",
        "compare_at_price": null,
        "display_compare_at_price": null
      },
      "relationships": {
        "product": {
          "data": {
            "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
            "type": "product"
          }
        },
        "images": {
          "data": []
        },
        "option_values": {
          "data": [
            {
              "id": "69485fa2-3fc3-4d12-9b25-af2cbe2ac0bd",
              "type": "option_value"
            }
          ]
        }
      }
    },
    {
      "id": "b7838bbb-e498-4971-9dfa-de9f1b19cc28",
      "type": "option_value",
      "attributes": {
        "name": "Large",
        "presentation": "Large",
        "position": 3,
        "public_metadata": {}
      },
      "relationships": {
        "option_type": {
          "data": {
            "id": "143b3650-0f2f-49d2-8514-9efa52bc8cf0",
            "type": "option_type"
          }
        }
      }
    },
    {
      "id": "13fd26cd-0f16-4a52-aa51-88b5a4f01462",
      "type": "variant",
      "attributes": {
        "sku": "classic-varsity-top-large",
        "barcode": null,
        "weight": "0.0",
        "height": null,
        "width": null,
        "depth": null,
        "is_master": false,
        "options_text": "Size: Large",
        "public_metadata": {},
        "purchasable": true,
        "in_stock": true,
        "backorderable": true,
        "currency": "USD",
        "price": "60.0",
        "display_price": "$60.00",
        "compare_at_price": null,
        "display_compare_at_price": null
      },
      "relationships": {
        "product": {
          "data": {
            "id": "8ded1874-43e4-4ea1-85e2-d521d65e7fce",
            "type": "product"
          }
        },
        "images": {
          "data": []
        },
        "option_values": {
          "data": [
            {
              "id": "b7838bbb-e498-4971-9dfa-de9f1b19cc28",
              "type": "option_value"
            }
          ]
        }
      }
    }
  ]
}

Open source libraries to transform JSONApi to a flat JSON response

As you probably noticed the JSON response can sometimes be quite big and hard to follow. To ease working with included resources we recommend checking out one of the open-source libraries that can help deserialize responses.