From f7dccd1a0bde333db86b084db0de15e17f2b135c Mon Sep 17 00:00:00 2001 From: John Henderson Date: Mon, 12 Aug 2024 19:01:34 +0100 Subject: [PATCH] Add HTML documentation (#29) * docs: add html documentation * docs(html): using 1.1 version --- docs/index.html | 1288 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1288 insertions(+) create mode 100644 docs/index.html diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..2684ae6 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,1288 @@ + + + + + + + +Open Charging Network (OCN) Node Documentation + + + + + +
+
+
+
+

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":"dacb3996-af67-4da1-b8b2-9102562143c0","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, though there are currently some features missing:

+
+
+
    +
  • +

    The hubclientinfo module is still work in progress.

    +
    • +
  • +

    Hub-specific features such as broadcast push and intelligent routing are not included.

    +
    • +
+
+
+

See the issues page on Bitbucket for more.

+
+
+
+
+

Pagination and Proxying Resources

+
+
+

The OCN handles OCPI pagination requests in a special way. When sending a paginated request, for example, +to get the first 50 locations from a Charge Point Operator, the CPO will respond with a Link header which +only their OCN Node will be able to access.

+
+
+

Because of this, the OCN Node must proxy this header. The sender will receive from their OCN Node a Link +header such as https://some.ocn-node.net/ocpi/sender/2.2/locations/page/2 which will correspond to the +original CPO resource, for example, https://some.cpo.com/ocpi/cpo/2.2/locations?offset=100&limit=100.

+
+
+

Other examples of resources which require proxying include the Location header returned from the POST method +of the cdrs receiver interface, as well as any response_url used in the commands and charging profiles +modules.

+
+
+
+
+

Custom OCPI modules

+
+
+

The OCN supports the use of custom OCPI modules. Such modules can be registered with an OCN Node during +the credentials handshake.

+
+
+

When requesting version details from the node, the response will contain the following endpoints:

+
+
+
+
{
+  "identifier": "custom",
+  "role": "sender",
+  "endpoint": "https://some.ocn-node.net/ocpi/custom/sender"
+},
+{
+  "identifier": "custom",
+  "role": "receiver",
+  "endpoint": "https://some.ocn-node.net/ocpi/custom/receiver"
+}
+
+
+
+

This acts as a wildcard for all custom OCPI modules. Here’s how it works:

+
+
+
    +
  1. +

    CPO completes credentials handshake with OCN Node

    +
    +
      +
    1. +

      CPO fetches OCN Node versions, saves endpoint details for wildcard custom module

      +
      2. +
    2. +

      OCN Node fetches CPO versions, saves endpoint details for enriched-locations custom module

      +
      3. +
    +
    +
    2. +
  2. +

    CPO sends their custom module request to the OCN Node

    +
    +
      +
    1. +

      requests any HTTP method

      +
      2. +
    2. +

      places module name as first path variable, followed by any additional variables required by the +custom module: https://some.ocn-node.net/ocpi/custom/receiver/enriched-locations/location1

      +
      3. +
    3. +

      appends url-encoded queries and json body if necessary

      +
      4. +
    +
    +
    3. +
  3. +

    OCN Node routes the message to recipient’s OCN Node

    +
    +
      +
    1. +

      recipient’s OCN Node looks up enriched-locations in recipient’s endpoints

      +
      2. +
    2. +

      recipient’s OCN Node forwards the request to https://recipient.msp.com/ocpi/emsp/2.2/enriched-locations/location1

      +
      3. +
    +
    +
    4. +
+
+
+
+
+

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

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription

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.

+
+ +++++ + + + + + + + + + + + + + + +
TypeCard.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.

+
+ ++++++ + + + + + + + + + + + + + + + + +
ParameterTypeRequiredDescription

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.

+
+ ++++++ + + + + + + + + + + + + + + + + +
ParameterTypeRequiredDescription

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 module will be blocked/blacklisted for the specific sender. If an empty list of modules is sent then the sender is eligible to use all the modules. If +updating signatures, 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.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeRequiredDescription

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
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeCard.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
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeCard.Description

active

Boolean

1

States whether the list is active.

list

BasicRole

*

Roles in the list.

+
+
+
BasicRole class
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeCard.Description

country_code

CIString(2)

1

Country code of role.

party_id

CIString(3)

1

Party ID (Provider ID) of role.

+
+
+
WhiteListModules class
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeCard.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
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription

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
+ ++++ + + + + + + + + + + + + + + + + +
ValueDescription

whitelist

List of parties allowed to send messages to receiver.

blacklist

List of parties not allowed to send messages to receiver.

+
+
+
+
+
+
+ + + \ No newline at end of file