Custom Structures
Custom structures in Kinesis API provide a way to create reusable, complex data templates that can be referenced across multiple collections. They function as user-defined object types that encapsulate related fields, enabling more sophisticated data modeling than is possible with basic structures alone.
Understanding Custom Structures
While regular structures define individual fields within a collection, custom structures allow you to define composite data types with multiple fields grouped together. Think of them as objects or complex data types that:
- Act as templates for complex data
- Can be reused across multiple collections
- Encapsulate related fields
- Support nested data models
- Enable modular data design
Accessing Custom Structures
Custom structures are managed through the collection interface but have their own dedicated pages:
- Navigate to a project page
- Select a collection
- Find the "Custom Structures" section
- Click on a custom structure name to access its dedicated page
Creating a Custom Structure
To create a new custom structure:
- From a collection page, find the "Custom Structures" section
- Click the "Create New" button
- Fill in the required information:
- Name: A descriptive name for the custom structure
- ID: A unique identifier used in API references
- Description: An explanation of the custom structure's purpose
- Click "Create" to save the custom structure
Custom Structure Detail Page
After creating a custom structure, you can access its detail page by clicking on its name. The custom structure page allows you to:
- View and edit the custom structure's information
- Add structures (fields) to the custom structure
- Manage existing structures
- Delete the custom structure
Managing Custom Structure Information
From the custom structure page, you can modify various aspects:
Updating Custom Structure ID
- Click the "Update Custom Structure ID" button
- Enter the new ID in the modal
- Click "Submit" to save the changes
Updating Custom Structure Name
- Click the "Update Custom Structure Name" button
- Enter the new name in the modal
- Click "Submit" to save the changes
Updating Custom Structure Description
- Click the "Update Custom Structure Description" button
- Enter the new description in the modal
- Click "Submit" to save the changes
Adding Structures to a Custom Structure
To add a field to a custom structure:
- From the custom structure page, click the "Create New" button in the Structures section
- Fill in the field details:
- Name: Field name
- ID: Field identifier
- Description: Field description
- Type: Data type selection
- Additional properties like min/max values, default value, etc.
- Click "Create" to add the field
The process for adding fields to a custom structure is identical to adding structures to a collection. See the Structures documentation for more details on field types and properties.
Example Use Cases
Custom structures are particularly useful for:
Address Information
Create an "Address" custom structure with fields like:
- Street
- City
- State/Province
- Postal Code
- Country
This can then be used in "Customer", "Shipping", "Billing" and other collections.
Contact Details
Build a "Contact Info" custom structure containing:
- Phone
- Website
- Social Media Profiles
Product Specifications
Define "Product Specs" with varying attributes based on product type:
- Dimensions
- Weight
- Material
- Technical Specifications
Modifying Custom Structures
When you modify a custom structure by adding, changing, or removing fields, these changes affect all places where the custom structure is used. This provides a powerful way to update data models across your entire API without making changes in multiple locations.
However, be aware that:
- Removing fields from a custom structure could impact existing data
- Changing field types might require data migration
- Adding required fields to an existing custom structure could cause validation errors
Deleting Custom Structures
To delete a custom structure:
- From the custom structure page, click the "Delete Custom Structure" button
- Confirm the deletion in the modal that appears
⚠️ Warning: Deleting a custom structure will affect all places where it's used. Ensure it's not referenced by any other structures before deletion.
Best Practices
When working with custom structures:
- Descriptive Naming: Use clear, descriptive names that indicate the custom structure's purpose
- Logical Grouping: Group related fields that naturally belong together
- Appropriate Granularity: Create custom structures at the right level of detail
- Reusability: Design custom structures to be reusable across multiple collections
- Documentation: Add thorough descriptions to help team members understand the purpose and usage of each custom structure
- Versioning Strategy: Consider how to handle changes to custom structures over time
Related Documentation
- Collections - Managing collections that contain custom structures
- Structures - Understanding basic structures and field types
- Data - Working with data based on complex structures