Serialization
The EquiDeFi API uses the JSON:API v1.1 specification for request and response payloads. This ensures consistent and predictable structures across all endpoints, making it easier to integrate, validate, and consume API data.
Key Features:
- Standardized structure for resources (type, id, attributes)
- Relationship support for linked resources (e.g., investor, investment, offering)
- Sparse fieldsets and includes for optimized queries
- Consistent error formatting for validation and server errors
📘 Top-Level Keys Explained
Key | Description |
|---|---|
data | The primary resource object or array of objects being returned. Includes type, id, attributes, and relationships. |
included | An array of related resource objects referenced in the relationships section of the primary data. This avoids needing to make separate calls. |
relationships | Defines links to other resources (e.g. investor, offering). Used to establish references in a normalized way. |
attributes | The actual data fields for the resource (excluding relationships). These are flat key-value pairs. |
meta | Arbitrary metadata about the response — such as pagination, counts, or filters. Not part of the resource object. |
links | URLs related to the response, such as self, next, prev. These help clients navigate resources and pages. |
errors | Used when the request fails. Contains an array of structured error objects with status, title, and detail. |
🧠 Best Practices
- Use the include query parameter to load related data (e.g. ?include=investor,offering) and avoid multiple round-trips.
- Use fields[resource]=... to restrict the attributes returned for performance and security.
- Always check for an errors key in non-2xx responses.