REST API

The Bender Charge Controller provides a powerful REST API that allows you to interact with the controller programmatically. This document provides an overview of the API, its capabilities, authentication process, and basic usage examples.

1. What is the REST API?

The Charge Controller's REST API is a programmatic interface that enables:

• Retrieving current configuration settings
• Changing configuration settings
• Building mobile and web applications that interface with the Charge Controller
• Monitoring system state and charging transactions
• Managing user authorization and whitelisting
• Accessing log messages
• And more

The API follows REST principles and uses JSON for data exchange, making it easy to integrate with various programming languages and platforms.

2. Relevant parameters

Location in Config UI	Parameter	Value	Info
System > General	REST interface	Disabled
		Enabled (with UID)	Contains identifiable user information, only enable if the network is secure
		Enabled (without UID)	Doesn't contain identifiable user information, suitable for less secure networks or desirable if no identifiable user information is needed
Authorization > RFID Settings	RFID Mode	RFID/NFC hybrid	Needs to be set to this for the NFC API to work

3. API access methods

The API can be accessed through:

• HTTP - For remote access over a network connection
• NFC - For local access using NFC-enabled devices

3.1. NFC

To access the API from an NFC equipped smart phone, the Charge Controller emulates an NFC Type 4 Tag based on the following standards:

• Transmission: ISO 14443 A
• Data Interchange: ISO 7816-4
• Data Container: NDEF – NFC Data Exchange Format – Text Record Type Messages

3.1.1. Activation

The RFID reader used can be operated in two modes:

• RFID only: only RFID cards can be read
• RFID/NFC hybrid: NFC communication is supported and RFID cards can be read

Since the basic functionality of a Charging Station is reading RFID cards, the default mode of the reader is RFID only.

See here for how to change the mode.

In RFID/NFC hybrid mode, the reader checks for both RFID and NFC communication until one of them is detected, afterwards this one will automatically be used. In case of NFC this means emulating an NFC Type 4 Tag which will be used for the data interchange between smart phone and Charge Controller via read/write operations.

Once NFC communication is established, the user interface of the Charging Station will display the corresponding pattern of the HMI state "Reading card".

3.1.2. Timeout

After one minute of inactivity, the RFID reader will switch back to RFID/NFC checking and the HMI will transition to the appropriate HMI state which is depending on the Charging Station state.

4. Authentication flow

The REST API is password protected. To use the API, you must authenticate following this process:

1. Request a token - Get a one-time token from the /login endpoint
2. Hash the password - Combine the password with the token and create a SHA-256 hash (SHA256(password + token))
3. Authenticate - Send the username and hashed password to the /login endpoint
4. Use the session ID - Include the returned session ID in all subsequent API requests
5. Maintain the session - The session times out after 60 seconds of inactivity

4.1. Important authentication notes

• Each token is valid for only one login attempt
• Only one client can be logged in at a time (logging in via another interface invalidates the current session)
• Include the session ID in the HTTP 'Authorization' header for all API calls
• Use the /logout endpoint to properly terminate a session

5. Next steps

For more detailed information about the REST API:

• See the API Reference for a complete list of endpoints and parameters
• Check out the Starters page for ready-to-use code examples

6. API versioning

The current version of the REST API is v1.0. The API endpoints are prefixed with /v1 to ensure compatibility as the API evolves.

7. Security considerations

When implementing applications that use the REST API:

• Store credentials securely
• Use HTTPS when available
• Implement proper error handling
• Logout when the session is no longer needed
• Consider implementing automatic re-authentication for long-running applications