Intro to Charge-Location Management API

📘

Beta

The Charge-Location Management API will be made available over the course of Q4 2022 to our Customers for feedback. On an invite-only basis, we would like for our Customer to test the new functionality and provide feedback.

During this time, GreenFlux reserve the right to make breaking changes with shorter notice periods than usual. Until GreenFlux has officially indicated that it is a stable API, we ask Customers not to build any business critical processes on top of this API.

Intro

GreenFlux is releasing a new set of APIs called 'Location & Charge Station Management APIs'.

These APIs have the following new properties:

  • ability to write, e.g. create Location & Charge Station (as opposed to only read)
  • additional fields (e.g. CS configuration fields) to populate your data warehouses

Until a definitive API documentation is released, this section outlines the current state of the API

Use Cases

Use CaseDescription
Get Charge Stations and Locations in batchGet a list of charge stations and locations that have recently been updated. Used for populating an external data warehouse.
Get Charge Stations and Locations in real timeGet multiple/single charge stations and locations in real time for use in an external Portal.
Create/Update/Patch single charge stations and locationsChanges should be available in real time.
Batch Create/Update/Patch single charge stations and locationsChanges should be available in real time.
Manage Charge Station hardware templates.Can get all hardware templates for a CPO and create/update templates. These templates can be used to manage charge stations.

Who should use these APIs?

  • Every CPO currently using the Locations API (v1.0) should migrate to the Locations v 2.0 endpoint as it has additional fields and additional functionality
  • CPOs who want to integrate their own CRM/Asset management system more closely. We are aware of some CPOs who have built front-ends for their end Customers. The new APIs would also allow them to e.g. change tariff codes, change opening hours or availability of a Charge Station
  • Build third-party installer Apps. An installer could use a custom built app to link a just-placed Charge Station with a Location and perform basic tests, instead of having to contact central support
  • Populate data-warehouses for further analytics. Our APIs will perform better for larger data polling and are complete

Design Principles - OCPI based

The current 'Platform APIs' are strongly based on OCPI, since originally they were just forked from the roaming side and made available to CPOs to retrieve their own data.

We believe that amongst our CPO Customers there is generally a good understanding of OCPI APIs and therefore these APIs are designed to stay as close as possible to the OCPI documentation.

Examples:

  • use of the data property for a data object or list of objects
  • The response format uses the data object, status code, status message and timestamp
  • reuse naming convention from OCPI as much as possible
  • same syntax (e.g. camel_case)
  • Same request format: use of offset, date_from, date_to and limit
  • authorization method

Key Changes

Locations

We have largely made the Locations object backwards compatible with OCPI 2.1.1.

As we already did in the previous iteration, we have added additional, custom GreenFlux fields to the object, such as:

  • auth_list
  • Custom group
  • Notes and remarks
  • Energy Profile Mix

New is also the ability to create, update and patch a Location object.

Charge Station

The Charge Station object does not exist in OCPI, so we have used the current structure that is in the Portal as a basis.

In principle, any field that is visible and editable in the EvPortal for a Charge Station can be updated via the API (except for Configuration, which will be addressed in future APIs)

Key elements

  • the EVSEs reside in the Charge Station object. Changes to an EVSE will update the parent Location object
  • Charge stations can be created and updated in a similar way as in the Portal
  • Key configuration items will be made available as read-only
    (Configuration changes are not yet able via API)

Error Codes

For these APIs, we follow OCPI guidelines. They state that:
If a request is syntactically valid JSON and addresses an existing resource, a HTTP error MUST NOT be returned. Those requests are supposed to have reached the OCPI layer.

OCPI error code ranges.

RangeDescription
1xxxSuccess
2xxxClient errors – The data sent by the client can not be processed by the server
3xxxServer errors – The server encountered an internal error

This means that e.g. a POST request to create a Location that is missing a required field will return a HTTP 200 code, but will have a OCPI 2000 status.

747747

Another example of a PUT upsert where the etag is out of date:

729729