Best Practices

1. Use Appropriate Query Parameters: Always specify relevant parameters like polymorphic, includeMeta to optimize responses; 2. Context Management: Ensure proper context switching when working across multiple contexts (by switching the token); 3. Error Handling: Implement proper retry logic for 403 (Forbidden) errors which may indicate context issues; 4. Resource Relationships: Always validate Entities and Relationships (e.g. every Resource must have at least one Facet); 5. Schema Validation: Define proper types before creating instances to ensure data consistency.

Troubleshooting

Common Issues:

Authentication Errors (401/403): - Check token expiration and refresh if necessary; - Ensure the token has access to the target context.

Resource Not Found (404): - Verify the resource UUID and type are correct; - Check if the resource exists in the current context; - Use sharing endpoints to add the resource to your context.

Validation Errors (400): - Check JSON payload format and required fields; - Verify the resource conforms to its type schema; - Ensure all mandatory relationships are present.

Debugging Tips:

  • Include includeMeta=true to see creation and modification metadata;

  • Use access endpoints for read-only exploration;

  • Check the Postman collection for working examples.