OCPI 2.3.0 Chapter 6

Versions Module

The required base module of OCPI. This module is the starting point for any OCPI connection. Via this module, clients can learn which versions of OCPI a server supports, and which modules it supports for each of the versions.

5 Sections

2 Endpoints

9 Modules

1. Overview

Introduction

About the Module

This is the required base module of OCPI. The Versions module is the starting point for any OCPI connection. Via this module, clients can learn which versions of OCPI a server supports, and which modules it supports for each of the versions.

Version Information Endpoint

Lists all available OCPI versions and the corresponding URLs to where version specific details can be found.

Version Details Endpoint

Provides information about which modules are implemented for a specific version, which interface role is implemented, and the endpoint URL for each interface.

Configuration Module

Type: Configuration Module. This module is required for all OCPI implementations. Both CPOs and eMSPs MUST implement the Version Information Endpoint and the Version Details Endpoint. The exact URL to the implemented version endpoint should be given (offline) to parties that want to communicate with your OCPI implementation.

2. Version Information Endpoint

6.1

This endpoint lists all the available OCPI versions and the corresponding URLs to where version specific details such as the supported endpoints can be found.

Endpoint Structure

No structure defined. This is open for every party to define themselves.

Endpoint URL Examples

https://www.server.com/ocpi/cpo/versions
https://www.server.com/ocpi/emsp/versions
https://ocpi.server.com/versions

The exact URL to the implemented version endpoint should be given (offline) to parties that want to communicate with your OCPI implementation.

Both, CPOs and eMSPs MUST implement such a version endpoint.

Methods

Method	Description
`GET`	Fetch information about the supported versions.

6.1.1. Data

Type	Card.	Description
`Version`	`+`	A list of supported OCPI versions.

6.1.2. Version class

Property	Type	Card.	Description
`version`	`VersionNumber`	`1`	The version number.
`url`	`URL`	`1`	URL to the endpoint containing version specific information.

6.1.3. GET

Fetch all supported OCPI versions of this CPO or eMSP.

6.1.3.1. Example — GET Version Information

[
  {
    "version": "2.1.1",
    "url": "https://www.server.com/ocpi/2.1.1"
  },
  {
    "version": "2.2.1",
    "url": "https://www.server.com/ocpi/2.2.1"
  }
]

3. Version Details Endpoint

6.2

Via the version details, the parties can exchange which modules are implemented for a specific version of OCPI, which interface role is implemented, and what the endpoint URL is for this interface.

Parties that are both CPO and eMSP (or a Hub) can implement one version endpoint that covers both roles. With the information that is available in the version details, parties don't need to implement a separate endpoint per role (CPO or eMSP) anymore. In practice this means that when a company is both a CPO and an eMSP and it connects to another party that implements both interfaces, only one OCPI connection is needed.

NOTE: OCPI 2.2 introduced the role field in the version details. Older versions of OCPI do not support this.

Endpoint Structure

No structure defined. This is open for every party to define themselves.

Endpoint URL Examples

https://www.server.com/ocpi/cpo/2.2.1
https://www.server.com/ocpi/emsp/2.2.1
https://ocpi.server.com/2.2.1/details

This endpoint lists the supported endpoints and their URLs for a specific OCPI version. To notify the other party that the list of endpoints of your current version has changed, you can send a PUT request to the corresponding credentials endpoint (see the credentials chapter).

Both the CPO and the eMSP MUST implement this endpoint.

Methods

Method	Description
`GET`	Fetch information about the supported endpoints for this version.

6.2.1. Data

Property	Type	Card.	Description
`version`	`VersionNumber`	`1`	The version number.
`endpoints`	`Endpoint`	`+`	A list of supported endpoints for this version.

6.2.2. Endpoint class

Property	Type	Card.	Description
`identifier`	`ModuleID`	`1`	Endpoint identifier.
`role`	`InterfaceRole`	`1`	Interface role this endpoint implements.
`url`	`URL`	`1`	URL to the endpoint.

NOTE: For the credentials module, the value of the role property is not relevant as this module is the same for all roles. It is advised to send "SENDER" as the InterfaceRole for one's own credentials endpoint and to disregard the value of the role property of the Endpoint object for other platforms' credentials modules.

4. Data Types

Reference

6.2.3. InterfaceRole enum

Value	Description
`SENDER`	Sender Interface implementation. Interface implemented by the owner of data, so the Receiver can Pull information from the data Sender/owner.
`RECEIVER`	Receiver Interface implementation. Interface implemented by the receiver of data, so the Sender/owner can Push information to the Receiver.

6.2.4. ModuleID OpenEnum

The Module identifiers for each endpoint are described in the beginning of each Module chapter. The following table contains the list of modules in this version of OCPI. Most modules (except Credentials & Registration) are optional, but there might be dependencies between modules. If there are dependencies between modules, it will be mentioned in the affected module description.

Module	ModuleID	Remark
CDRs	`cdrs`
Charging Profiles	`chargingprofiles`
Commands	`commands`
Credentials & Registration	`credentials`	Required for all implementations. The role field has no function for this module.
Hub Client Info	`hubclientinfo`
Locations	`locations`
Sessions	`sessions`
Tariffs	`tariffs`
Tokens	`tokens`

6.2.5. VersionNumber OpenEnum

List of known versions.

Value	Description
`2.0`	OCPI version 2.0
`2.1`	OCPI version 2.1 DEPRECATED (DEPRECATED, do not use, use 2.1.1 instead)
`2.1.1`	OCPI version 2.1.1
`2.2`	OCPI version 2.2 DEPRECATED (DEPRECATED, do not use, use 2.2.1 instead)
`2.2.1`	OCPI version 2.2.1
`2.3.0`	OCPI version 2.3.0 this version

6.2.5.1. Custom Modules

Parties are allowed to create custom modules or customized versions of the existing modules. To do so, the ModuleID enum can be extended with additional custom moduleIDs. These custom moduleIDs MAY only be sent to parties with which there is an agreement to use a custom module. Do NOT send custom moduleIDs to parties you are not 100% sure will understand the custom moduleIDs.

It is advised to use a prefix (e.g. country-code + party-id) for any custom moduleID, this ensures that the moduleID will not be used for any future module of OCPI.

Custom ModuleID Example

nltmn-tokens

5. GET Examples

6.2.6

Fetch information about the supported endpoints and their URLs for this OCPI version.

Simple CPO Example

Simple version details example: CPO with only 2 modules.

GET Version Details — CPO with 2 modules

{
  "version": "2.2",
  "endpoints": [
    {
      "identifier": "credentials",
      "role": "SENDER",
      "url": "https://example.com/ocpi/2.2/credentials"
    },
    {
      "identifier": "locations",
      "role": "SENDER",
      "url": "https://example.com/ocpi/cpo/2.2/locations"
    }
  ]
}

CPO + eMSP Example

Simple version details example: party with both CPO and eMSP with only 2 modules. In this case the credentials module is not defined twice as this module is the same for all roles.

GET Version Details — CPO + eMSP combined

{
  "version": "2.2",
  "endpoints": [
    {
      "identifier": "credentials",
      "role": "RECEIVER",
      "url": "https://example.com/ocpi/2.2/credentials"
    },
    {
      "identifier": "locations",
      "role": "SENDER",
      "url": "https://example.com/ocpi/cpo/2.2/locations"
    },
    {
      "identifier": "tokens",
      "role": "RECEIVER",
      "url": "https://example.com/ocpi/cpo/2.2/tokens"
    },
    {
      "identifier": "locations",
      "role": "RECEIVER",
      "url": "https://example.com/ocpi/msp/2.2/locations"
    },
    {
      "identifier": "tokens",
      "role": "SENDER",
      "url": "https://example.com/ocpi/msp/2.2/tokens"
    }
  ]
}