The following documentation provides usage details, with examples, for administrators and users of an OCN Node. It assumes that the node has already been set up according to instructions provided in the repository.

Health

The health endpoint can be used to ensure that the message broker is reachable via HTTP.

Request

GET /health HTTP/1.1
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 2

OK

Registry

The registry API provides helpful OCN Registry queries. The registry smart contract itself holds information about parties and nodes on the network. By extension, the following API can be used to check whether the OCN Node has been correctly configured to interact with the registry smart contract.

Get Node Information

This endpoint retrieves the publicly available information (root public URL, Ethereum wallet address) of a given OCN Node. This information should match the OCN Registry listing of the OCPI party using the Node.

Request

GET /ocn/registry/node-info HTTP/1.1
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 85

{"url":"https://node.ocn.org","address":"0x9bc1169ca09555bf2721a5c9ec6d69c8073bfeb4"}

Get Party’s Node Information

This endpoint is used to find the OCN Registry listing of a given party. Two url path variables should be provided: the OCPI country_code and party_id.

Request

GET /ocn/registry/node/DE/ABC HTTP/1.1
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 85

{"url":"https://node.ocn.org","address":"0x22D44D286d219e1B55E6A5f1a3c82Af69716756A"}

Admin

The admin API allows administrators to manage their OCN Node. Currently, the only admin functionality is the generatoion of new Open Charge Point Interface registration tokens (so-called CREDENTIALS_TOKEN_A) for interested platforms.

Request

POST /admin/generate-registration-token HTTP/1.1
Content-Type: application/json
Authorization: Token 1234567890
Content-Length: 40
Host: localhost:8080

[{"party_id":"SNC","country_code":"DE"}]

The Authorization header should be set in the format Token ${api_key}. The admin can find this in stdout when the application runs (a new key will be generated each time unless specified in the application’s properties file).

Body

[{"party_id":"SNC","country_code":"DE"}]

The request body is a list of a platforms' roles, containing their party_id and country_code. This allows a platform with multiple OCPI roles (i.e. EMSP and CPO) to register on the same OCPI connection.

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 96

{"token":"f4c714de-c592-4a1d-b1a0-ab188b8623de","versions":"https://node.ocn.org/ocpi/versions"}

The response contains the OCPI TOKEN_A and the message broker’s versions endpoint, both of which are needed to start the registration process.

Open Charge Point Interface

The Open Charge Point Interface enables eMobility platforms to connect to one another. The Open Charging Network uses this as it’s primary means of connecting such parties. It is important to have developed an OCPI version 2.2 API beforehand, in order to connect to and use an OCN Node. This comprises, as a bare minimum, the credentials module. Documentation for version 2.2 can be found on OCPI @ GitHub.

The node strives to provide all the functionality of OCPI. As this software is in alpha stage, there are currently some features of OCPI missing:

  • hubclientinfo module is only partly implemented.

  • Hub-specific features such as broadcast push and intelligent routing are missing.

OcnRules module

Module Identifier: ocnrules

Type: Configuration Module

OCN Nodes provide an additional, optional OCPI module: OcnRules. This allows platforms to configure filtering rules for their chosen OCN Node. Current filtering rules include: overriding OCN signature requirement preferences; blacklisting and whitelisting. Note that the blacklist and whitelist cannot be active at the same time. If the whitelist is active, all senders not on the whitelist will have their requests filtered by the OCN Node (they will not reach the receiver). Likewise, if the blacklist is active, all requests will reach the platform except those from senders specified on the blacklist.

The signature rules allows the default OCN signature header requirement of the OCN Node to be overruled by the receiving platform. By default, the value will match that of the OCN Node. The platform can set signatures to be required even if the OCN Node does not do so by default. Note that the other way is not possible - a platform cannot tell the OCN Node to turn off signature verification.

Interfaces

The OcnRules module only specifies a receiver interface, implemented by the OCN Node itself. Connected platforms use this interface to update rules on their given OCN Node.

Receiver Interface

Endpoint structure: /ocpi/receiver/2.2/ocnrules

Method Description

GET

Retrieve the full list of rules as stored on the platform’s OCN Node.

POST

Add a single rule entry, for example to the whitelist or blacklist.

PUT

Update a rule

PATCH

n/a

DELETE

Delete a single rule entry
GET Method

Used by a platform to check their rules as stored on their OCN Node.

Response Data

The response contains the requested object.

Type Card. Description

OcnRules

1

The requested OcnRules object.
POST Method

New rules entries are updated by the platform on the OCN Node. Applies to whitelist and blacklist.

Request parameters

The following parameter can be provided as URL segment.

Parameter Type Required Description

create_list_type

OcnRulesListType

yes

The type of list which the new entry applies to.
Request Body

Body is required if sending a POST request to whitelist or blacklist.

Type

Card.

Description

country_code

CIString(2)

Country code of role to add to the specified list

party_id

CIString(3)

Party ID (Provider ID) of role to add to the specified list

WhiteListModules

*

The counterparty role and list of modules information to add to the specified list.
Example: add party to blacklist
POST to URL: https://node.ocn.org/ocpi/receiver/2.2/ocnrules/blacklist

    {
        "country_code": "DE",
        "party_id": "ABC",
        "modules": ["cdrs", "locations"]
    }
PUT Method

Updates all rules entries for a platform on the OCN Node. Applies to signatures, whitelist and blacklist.

Parameter Type Required Description

list_type

OcnRulesType

yes

The type of rule to update.
Request Body

Body is required if sending a PUT request to whitelist or blacklist. If an empty list is sent, the OCN Node will interpret that as the deletion of all rules for the given list. Therefore, the specified list will be deactivated. It is also mandatory to set which specific modules will be blocked/blacklisted for the sender. If an empty list of modules is sent then the sender is eligible to use all the modules. If updating signatures or setting block-all, then no body is required.

Type

Card.

Description

BasicRole

*

The counter-party role information to add to the specified list.

WhiteListModules

*

The counter-party role and list of modules information to add to the specified list.
Example: update whitelist
PUT to URL: https://node.ocn.org/ocpi/receiver/2.2/ocnrules/whitelist

[
  {
    "country_code": "DE",
    "party_id": "ABC",
    "modules": ["cdrs", "locations"]
  },
  {
    "country_code": "CH",
    "party_id": "DEF",
    "modules": ["sessions", "tokens"]
  }
]
Example: update signatures toggle

There is no request body required for this request. The value will be set to the opposite of the current value (true or false).

PUT to URL: https://node.ocn.org/ocpi/receiver/2.2/ocnrules/signatures
DELETE Method

Removes a single entry from a rules list. Applies to the whitelist and blacklist.

Request parameters

The following parameters can be provided as URL segments.

Parameter Type Required Description

list_type

OcnRulesListType

yes

The type of list which the new entry applies to.

country_code

CIString(2)

yes

Country code of role to add to the specified list

party_id

CIString(3)

yes

Party ID (Provider ID) of role to add to the specified list
Example: remove party from blacklist
DELETE to URL: https://node.ocn.org/ocpi/receiver/2.2/ocnrules/blacklist/NL/XYZ

Object Description

OcnRules Object
Property Type Card. Description

signatures

Boolean

1

States whether request signature verification is enabled.

whitelist

OcnRulesList

1

Whitelist rules.

blacklist

OcnRulesList

1

Blacklist rules.

Data Types

OcnRulesList class
Property Type Card. Description

active

Boolean

1

States whether the list is active.

list

BasicRole

*

Roles in the list.
BasicRole class
Property Type Card. Description

country_code

CIString(2)

1

Country code of role.

party_id

CIString(3)

1

Party ID (Provider ID) of role.
WhiteListModules class
Property Type Card. Description

country_code

CIString(2)

1

Country code of role.

party_id

CIString(3)

1

Party ID (Provider ID) of role.

modules

ModuleID

*

A list of 0 or more
OcnRulesType Enum
Value Description

signatures

Parties must include valid OCN Signature header in requests to receiver.

whitelist

List of parties allowed to send messages to receiver.

blacklist

List of parties not allowed to send messages to receiver.

block-all

Enable an empty whitelist, effectively blocking all incoming requests.
OcnRulesListType Enum
Value Description

whitelist

List of parties allowed to send messages to receiver.

blacklist

List of parties not allowed to send messages to receiver.