Introduction

The following document defines the web services supported by the ABS.

JSON Restful

The ABS web services are based on REST principles. Data is sent in GET (retrieval), POST (creation/start), DELETE (delete/stop) or PUT (update) methods to the web service URI mentioned below. For instance for the starting, updating and ending of sessions, data is sent to the /abs/cs/session URI using POST, PUT and DELETE methods respectively. The HTTP response contains the result in JSON format. Please see the REST article on Wikipedia for more information.

Data is exchanged using the JSON data-interchange format. Please see the JSON specification for more information.

General remarks

All input parameters mentioned in the descriptions below should be passed to the web service via URI parameters (i.e. POST /abs/frontend/zone?name=MyZoneName)

Parameters must be URL encoded.

Response output parameters are always sent as JSON objects. The object will contain a “statusCode” field that indicates the result of the operation.

For “update” web services, only the parameters that have been passed will be updated. I.e. if a charging station has a latitude and longitude, if only the latitude is passed in an update web service, the longitude will not be modified.

The HTTP method depends on which kind of action is taken. In general: - GET is for retrieval. - POST is for creation. - PUT is for updating. - DELETE is for deletion.

In this document, optional query parameters are indicated by a question mark. (The question mark is not part of the parameter name.)

Please note that all timestamps passed to the ABS should be encoded as Unix UTC timestamps, i.e. seconds since midnight UTC, 1 January 1970.

The endpoint URL for the API is https://api.becharged.eu/.

Authentication

The ABS system will be secured by session authentication over SSL. For details on obtaining session IDs and subsequently using these sessions in requests, please see Authentication services. Specific operations are only available to particular user roles. For instance, only hosts can create charging stations, but all users can retrieve (GET) charging stations.

Retrieval (GET) methods will return entries that are visible to the requesting user. For instance, a host requesting an overview of all zones will only receive a list of zones that the particular host has created. A host cannot see another host’s zones. However, if an administrator or an operator requests a list of all zones, all zones in the system will be returned.

Methods that modify data (PUT or DELETE) can only modify entries that are visible to the requesting user. For instance, a host can only delete a zone that was created by that same host previously. Likewise, a host can only modify a zone or create a charging server in a zone that he or she created.

User roles

The ABS distinguishes two general user categories:

  • administration users (role name user): persons with access to the administration functions of the ABS,
  • the charging station interface account, with role name cs.

Administration users start out with essentially no more access to the system than an anonymous user. To gain access, they need to be granted additional roles:

  • host: allows viewing of charging station-related information.
  • hostAdmin: also allows modification of charging station-related information.
  • evAdmin: allows access to the EV driver management functions.
  • userAdmin: allows access to the administration user management functions.

Lastly, there is an admin role which grants full access to the system.

Status codes

Warning

Status codes are encoded as strings in server responses.

Code Meaning
100 The operation completed successfully.
 
201 Unknown user.
202 Unknown socket.
203 Unknown session.
204 Unknown charging station.
205 Unknown zone.
207 Unknown EV driver.
208 Unknown pricing policy.
210 Unknown alert.
212 Unknown RFID.
213 Unknown role.
214 Unknown account.
215 Unknown notification rule.
216 Unknown device.
217 Unknown vehicle.
218 Unknown device command.
219 Unknown device file upload.
220 Unknown device message.
 
301 Incorrect timestamp provided.
302 The session cannot be started as another session is currently running for this user.
303 The session cannot be updated as it has already been ended.
304 A zone with that name already exists.
305 A charging station with that name already exists.
307 A socket with this device rank already exists for this charging unit.
311 The session cannot be started as the socket is not available.
313 The provided username is already in use.
314 The provided email address is already registered.
315 The session cannot be started as the user has not been activated.
316 The socket operation cannot be completed as the socket has already been reserved.
317 The socket operation cannot be completed as the socket is not available.
318 The socket reservation cannot be made as the EV driver has already reserved a socket.
319 No charging session found for EV driver.
320 The EV driver has no active socket reservation.
322 The provided token string already exists.
323 The token cannot be deleted as it is currently assigned to an EV driver.
324 The EV driver is not allowed to use this charging station.
325 A device with that serial number already exists.
326 The socket is not reserved.
327 Too many vehicles; no more vehicles can be defined.
328 The device cannot accept commands because it does not have a network connection.
 
444 Authentication failed.
445 Session-Id invalid or expired.
 
666 Invalid parameter semantics.
777 Invalid parameter(s) supplied.
888 Missing parameter(s).
999 Any other error.
 
1001 The smartgrid is not enabled on this charging station.
1002 The smartgrid failed because there was no power set.

If an operation completes successfully, it will return with status code 100.

Each service defined below lists the possible return codes it can generate. Error codes 100, 666, 777, 888 and 999 can be generated for any operation and might not be mentioned explicitly below:

  • If all parameters were supplied with legal values but the combination of parameters is incorrect, error code 666 will be returned.
  • If all parameters were supplied but have illegal values status code 777 will be returned. This is also true for semantic value errors (i.e. a negative time value).
  • If a parameter was missing from an operation status code 888 will be returned.
  • If anything else goes wrong during the execution of the service, error code 999 will be returned.

Please note that all 2xx class error codes will also be raised if a user tries to access a resource that is not visible to him or her.

Note

Omitting a required parameter will usually result in a HTTP 400 error instead of a reply with status code 888.

Note

Requests with an invalid or an expired ABS-Session-Id header will generate a JSON reply with statusCode 445. This reply will be sent with a HTTP error code 403.

Authentication services

The following web services are available for authentication purposes.

POST /abs/authentication

Start an API session. The response includes the session id, the user’s roles in the userType array (see User roles) and the user’s preferred language.

Form Parameters:
 
  • username – The requesting user’s username
  • password – The requesting user’s password
Status Codes:
  • 100 – The operation completed successfully.
  • 444 – Authentication failed.

Example response

{ "statusCode": "100",
  "sessionId": "A249A98B9F77B5C2D12BCE898381A80F",
  "userType": ["host"],
  "language": "nl" }

Once a session ID has been obtained, access to protected web services can be obtained. This can be done by including the session ID in an ABS-Session-Id HTTP header:

ABS-Session-Id: A249A98B9F77B5C2D12BCE898381A80F

If a session is not used for a period of sixty minutes, it will expire and a new session will have to be obtained. It is also possible to explicitly terminate sessions.

DELETE /abs/authentication

Delete all the user’s sessions.

Status Codes:
  • 100 – The operation completed successfully.