Skip to content
/
Expanding Responses
Last updated

Expanding Responses

In order to reduce the number of requests to the API that your client needs to make, you can use the expand query parameter to included nested information in responses.

Whenever a resource references another resource via a URL, you can use the expand parameter to replace that URL with a nested representation of the resource. For example, if you request an EVSE, you will get a link to that EVSE's model:

GET https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y
{
  "id": "evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "url": "https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "model": "https://api.ev.energy/v2/evse_models/emod01HN2NJHAJJAQD32QJ4QXTDSGW",
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
}

If you add ?expand=model you can get the details for the Model at the same time:

GET https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y?expand=model
{
  "id": "evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "url": "https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "model": {
    "id": "emod01HN2NJHAJJAQD32QJ4QXTDSGW",
    "name": "BG SyncEV",
    "make": "https://api.ev.energy/v2/evse_makes/emak01HN2NJQRGDQP0GBE1F7R6PB3D",
  },
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
}

You could also expand the user resource at the same time by adding two instances of the expand query param: ?expand=model&expand=user.

The "Try it" mock server in these docs returns static examples and does not apply expand; for charging sessions, send the header x-redocly-response-body-example: expanded_sub_sessions to get the example with sub_sessions expanded.

Nested expansion

The API also supports multiple levels of nesting by chaining field names with .s. For example, to get the model and make of an EVSE, you could use expand=model.make:

GET https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y?expand=model,make
{
  "id": "evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "url": "https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "model": {
    "id": "emod01HN2NJHAJJAQD32QJ4QXTDSGW",
    "url": "https://api.ev.energy/v2/evse_models/emod01HN2NJHAJJAQD32QJ4QXTDSGW",
    "name": "BG SyncEV",
    "make": {
      "id": "emak01HN2NJQRGDQP0GBE1F7R6PB3D",
      "url": "https://api.ev.energy/v2/evse_makes/emak01HN2NJQRGDQP0GBE1F7R6PB3D",
      "name": "BG"
    },
  },
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
}

Permissions

Expanding a resource requires your token to have the same scopes you would need to make the corresponding request. For example, to expand user on a Vehicle, you need user:read as well as vehicle:read. Lacking a required scope will result in a 403 error.

Errors

If you pass a value to expand which cannot be expanded (such as the resource's id, a field that isn't present, or a recursive nested expansion like latest_status_log.vehicle) a 400 Bad Request response will be generated, with a problem type of http://api.ev.energy/v2/problems/unexpandable-property/.

Pagination

Rate limits