Expanding responses

By default, certain fields in response objects may contain only an ID of a related object. The expand parameter enables you to request the full details for these related objects directly within the initial response. For example, by default, a "session" object might have an associated user ID. However, with the expand parameter you can request the full user information to be included in the response.

The documentation for each endpoint specifies which fields are expandable.

Usage

The expand parameter is always an array, allowing for multiple fields to be expanded in the same request. This parameter can be used in any API endpoint that supports expansion, including those for listing resources and endpoints for creating or updating resources.

Example

curl -X GET 'https://api.emogg.com/v1/sessions?expand[]=user' \
     -H 'Authorization: Bearer YOUR_API_TOKEN'

By using the expand parameter, you can reduce the number of API calls required to gather related information, making your application more efficient and providing a smoother user experience.

Expanding nested fields

For fields that are themselves objects containing other expandable fields, you can use dot notation to specify nested fields to be expanded. Example: field_a.field_b.

When expanding objects within a list, you do not include the data field on the path. For example, for expanding user field in a list the path must be just user and NOT data.user.

Expanding recursively

At this moment, expanding fields recursively is not supported. For example, if you want to expand both the field "session" and the field "user" inside of the expanded session object, specifying "session.user" in the expand parameter will not work.