Venddor API - Nested Objects

Working with Nested Objects

The Venddor API frequently returns and accepts complex data structures with nested objects. This documentation explains how to work with nested objects effectively in the API.

Key Concepts:

Types of Nested Objects

Several types of objects in the Venddor API contain nested structures:

Products

Product objects often contain nested objects for:

{
  "product_id": "42",
  "product": "Premium T-shirt",
  "price": "29.99",
  "category_ids": ["12", "15"],
  "options": {
    "4": {
      "option_id": "4",
      "option_name": "Size",
      "option_type": "S",
      "variants": {
        "12": {
          "variant_id": "12",
          "variant_name": "Small"
        },
        "13": {
          "variant_id": "13",
          "variant_name": "Medium"
        },
        "14": {
          "variant_id": "14",
          "variant_name": "Large"
        }
      }
    }
  },
  "main_pair": {
    "pair_id": "56",
    "image_id": "78",
    "detailed": {
      "image_path": "http://example.com/images/detailed/tshirt.jpg",
      "alt": "Premium T-shirt"
    }
  }
}

Categories

Category objects may include nested objects for:

{
  "category_id": "15",
  "category": "Men's Clothing",
  "parent_id": "5",
  "subcategories": [
    {
      "category_id": "18",
      "category": "T-shirts",
      "parent_id": "15"
    },
    {
      "category_id": "19",
      "category": "Pants",
      "parent_id": "15"
    }
  ],
  "image_pair": {
    "pair_id": "24",
    "detailed": {
      "image_path": "http://example.com/images/categories/mens.jpg"
    }
  }
}

Orders

Order objects typically contain nested objects for:

{
  "order_id": "1001",
  "status": "P",
  "user_id": "42",
  "products": [
    {
      "item_id": "101",
      "product_id": "42",
      "product": "Premium T-shirt",
      "price": "29.99",
      "amount": "2",
      "product_options": {
        "4": "13"
      }
    }
  ],
  "shipping_address": {
    "address_id": "15",
    "address": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "country": "US",
    "zipcode": "12345"
  },
  "payment_info": {
    "payment_id": "28",
    "payment_method": "credit_card",
    "status": "paid"
  }
}

Working with Nested Objects in API Requests

Accessing Nested Data

When working with responses containing nested objects, you'll need to traverse the object hierarchy to access specific data points:

// JavaScript example
const productName = response.product;
const size = response.options["4"].variants["13"].variant_name;
const imageUrl = response.main_pair.detailed.image_path;

Creating and Updating Nested Objects

When creating or updating objects with nested structures, you'll need to include the complete object hierarchy:

{
  "product": "New T-shirt",
  "price": "19.99",
  "options": {
    "4": {
      "option_name": "Size",
      "option_type": "S",
      "variants": {
        "0": {
          "variant_name": "Small"
        },
        "1": {
          "variant_name": "Medium"
        },
        "2": {
          "variant_name": "Large"
        }
      }
    }
  }
}
Tip: When updating nested objects, you can often update just a specific part of the nested structure without having to include the entire object. For example, to update just a product's price, you only need to include the product_id and price fields.

Best Practices for Working with Nested Objects

Data Validation

When working with complex nested objects, implement thorough validation:

// JavaScript validation example
function validateProduct(product) {
  // Validate top-level required fields
  if (!product.product || !product.price) {
    return false;
  }
  
  // Validate nested options if they exist
  if (product.options) {
    for (const optionId in product.options) {
      const option = product.options[optionId];
      if (!option.option_name || !option.option_type) {
        return false;
      }
      
      // Validate option variants if they exist
      if (option.variants) {
        for (const variantId in option.variants) {
          const variant = option.variants[variantId];
          if (!variant.variant_name) {
            return false;
          }
        }
      }
    }
  }
  
  return true;
}

Handling Missing Data

When accessing nested objects, use defensive programming to handle potentially missing data:

// JavaScript example with defensive programming
function getProductImage(product) {
  // Handle missing image data safely
  if (product && 
      product.main_pair && 
      product.main_pair.detailed && 
      product.main_pair.detailed.image_path) {
    return product.main_pair.detailed.image_path;
  }
  
  // Return default image if any part of the path is missing
  return 'http://example.com/images/default.jpg';
}

Working with Arrays of Nested Objects

Many API responses include arrays of nested objects. Use appropriate techniques to process these collections:

// JavaScript example with array processing
function getTotalOrderAmount(order) {
  if (!order.products || !Array.isArray(order.products)) {
    return 0;
  }
  
  return order.products.reduce((total, product) => {
    const price = parseFloat(product.price) || 0;
    const quantity = parseInt(product.amount) || 0;
    return total + (price * quantity);
  }, 0);
}

Common API Endpoints with Nested Objects

GET /products/{product_id}

Retrieves a product with all its nested data including options, variants, features, and images.

GET /categories/{category_id}?get_subcategories=Y

Retrieves a category with all its subcategories as nested objects.

GET /orders/{order_id}

Retrieves an order with nested data for products, customer details, and shipping information.

Important: When working with deeply nested objects, be mindful of potential performance impacts. Consider using fields filtering (if supported by the API) to retrieve only the necessary nested data when dealing with large objects.

Related Documentation

For more detailed information about specific object types and their nested structures, refer to the following documentation:

Copyright © . Venddor Tecnologia S.A. All rights reserved.