Transport and Format

The OCPI protocol is based on HTTP and uses the JSON format. It follows a RESTful architecture for web services where possible.

Authorization: Token ZWJmM2IzOTktNzc5Zi00NDk3LTliOWQtYWM2YWQzY2M0NGQyCg==

Authorization: Token ZXhhbXBsZXRva2Vu

4.1.3. Pull and Push

OCPI supports both Pull and Push models.

OCPI doesn't require parties to implement Push. Pull is required, a receiver needs to be able to get in-sync after a period of connection loss.

It is possible to implement a Pull only OCPI implementation, it might be a good starting point for an OCPI implementation. However, it is strongly advised to implement Push for production systems that have to handle some load, especially when several clients are requesting long lists frequently. Push implementations tend to use fewer resources.

It is therefore advised to clients pulling lists from a server to do this on a relatively low polling interval: think in hours, not minutes, and to introduce some splay (randomize the length of the poll interval a bit).

4.1.4. Request Format

The request method can be any of GET, POST, PUT, PATCH or DELETE. The OCPI protocol uses them in a way similar to REST APIs.

The HTTP header Content-Type SHALL be set to application/json for any request that contains a message body: POST, PUT and PATCH. When no body is present, probably in a GET or DELETE, then the Content-Type header MAY be omitted.

Link: <https://www.server.com/ocpi/cpo/2.2.1/cdrs/?offset=150&limit=50>; rel="next"

Link: <https://www.server.com/ocpi/cpo/2.2.1/cdrs/?offset=200&limit=50>; rel="next"

https://www.server.com/ocpi/cpo/2.2.1/cdrs/?date_from=2016-01-01T00:00:00Z&date_to=2016-12-31T23:59:59Z

Link: <https://www.server.com/ocpi/cpo/2.2.1/cdrs/?offset=100&limit=100&date_from=2016-01-01T00:00:00Z&date_to=2016-12-31T23:59:59Z>; rel="next"

https://www.server.com/ocpi/cpo/2.2.1/cdrs/?limit=2000

Link: <https://www.server.com/ocpi/cpo/2.2.1/cdrs/?offset=100&limit=100>; rel="next"

4.1.5. Client Owned Object Push

Normal client/server RESTful services work in a way where the Server is the owner of the objects that are created. The client requests a POST method with an object to the end-point URL. The response sent by the server will contain the URL to the new object. The client will request only one server to create a new object, not multiple servers.

Many OCPI modules work differently: the client is the owner of the object and only pushes the information to one or more servers for information sharing purposes. For example the CPO owns the Tariff objects and pushes them to a couple of eMSPs, so each eMSP gains knowledge of the tariffs that the CPO will charge them for their customers' sessions. eMSP might receive Tariff objects from multiple CPOs. They need to be able to make a distinction between the different tariffs from different CPOs.

The distinction between objects from different CPOs/eMSPs is made based on a {country_code} and {party_id}. The country_code's and party_id's of the parties on the other platform are received during the credentials handshake in the CredentialsRoles. The roles exchanged during the credentials handshake provide the server with details needed to determine which URLs a client might use.

Example of a URL to a Client Owned Object:

https://www.server.com/ocpi/cpo/2.2.1/tariffs/NL/TNM/14

POST is not supported for these kinds of modules. PUT is used to send new objects to the servers.

To identify the owner of data, the party generating the information that is provided to other parties via OCPI, a 'Data owner' is provided at the beginning of every module that has a clear owner.

4.1.6. Client Owned Object Pull

When doing a GET on the Sender interface of a module, the owner of an object can be determined by looking at the {country_code} and {party_id} in the object itself.

When one or more objects, returned in the response, do not meet one of the CredentialsRoles given during the credentials handshake, these objects may be ignored.

4.1.7. Response Format

The content that is sent with all the response messages is an application/json type and contains a JSON object with the following properties:

For brevity's sake, any further examples used in this specification will only contain the value of the data field. In reality, it will always have to be wrapped in the above response format.

When a request cannot be accepted, the type response depends on the type of error. For more information see: Status codes.

For errors on the HTTP layer, use HTTP error response codes, including the response format above, that contains more details. HTTP status codes are described on w3.org.

Response Examples

{
  "data": [{
      "version": "2.1.1",
      "url": "https://example.com/ocpi/cpo/2.1.1"
  }, {
      "version": "2.2",
      "url": "https://example.com/ocpi/cpo/2.2"
  }],
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2015-06-30T21:59:59Z"
}

{
  "data": {
      "version": "2.2",
      "endpoints": [{
          "identifier": "credentials",
          "role": "SENDER",
          "url": "https://example.com/ocpi/cpo/2.2/credentials"
      }, {
          "identifier": "locations",
          "role": "SENDER",
          "url": "https://example.com/ocpi/cpo/2.2/locations"
      }]
  },
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2015-06-30T21:59:59Z"
}

{
  "data": {
      "country_code": "DE",
      "party_id": "TNM",
      "uid": "012345678",
      "type": "RFID",
      "contract_id": "FA54320",
      "visual_number": "DF000-2001-8999",
      "issuer": "TheNewMotion",
      "valid": true,
      "whitelist": "ALLOWED",
      "last_updated": "2015-06-29T22:39:09Z"
  },
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2015-06-30T21:59:59Z"
}

{
  "data": [{
      "country_code": "NL",
      "party_id": "TNM",
      "uid": "100012",
      "type": "RFID",
      "contract_id": "FA54320",
      "visual_number": "DF000-2001-8999",
      "issuer": "TheNewMotion",
      "valid": true,
      "whitelist": "ALWAYS",
      "last_updated": "2015-06-21T22:39:05Z"
  }, {
      "country_code": "NL",
      "party_id": "TNM",
      "uid": "100013",
      "type": "RFID",
      "contract_id": "FA543A5",
      "visual_number": "DF000-2001-9000",
      "issuer": "TheNewMotion",
      "valid": true,
      "whitelist": "ALLOWED",
      "last_updated": "2015-06-28T11:21:09Z"
  }, {
      "country_code": "NL",
      "party_id": "TNM",
      "uid": "100014",
      "type": "RFID",
      "contract_id": "FA543BB",
      "visual_number": "DF000-2001-9010",
      "issuer": "TheNewMotion",
      "valid": false,
      "whitelist": "ALLOWED",
      "last_updated": "2015-05-29T10:12:26Z"
  }],
  "status_code": 1000,
  "status_message": "Success",
  "timestamp": "2015-06-30T21:59:59Z"
}

{
    "status_code": 2001,
    "status_message": "Missing required field: type",
    "timestamp": "2015-06-30T21:59:59Z"
}

4.1.8. Non-specified JSON Fields

An OCPI Platform SHALL NOT reject request or response payloads based on the presence of JSON object field names that are not documented in this specification.

OCPI implementers are encouraged to extend OCPI with new fields to address needs that are not foreseen by the specification and to adhere to the spirit of RFC 6648 when doing so.

When extending OCPI with such non-specified fields, implementers:

• SHOULD assume that their extensions will eventually be incorporated into OCPI or otherwise become widely used,
• SHOULD choose meaningful field names that are currently unused to the best of their knowledge,
• SHOULD NOT use name prefixes like x- or custom to indicate the non-specified nature of these field names, and
• SHOULD consult further guidance on extending OCPI at https://evroaming.org/extending-ocpi/.

4.1.9. Message Routing

When the development of OCPI was started, it was designed for peer-to-peer communication between CPO and eMSP. This has advantages, but also disadvantages. Having to set up and maintain OCPI connections to a lot of parties requires more effort than doing it for only a couple of connections. By communication via one or more Hubs, the amount of OCPI connections is reduced, while still being able to offer roaming to a lot of different parties and customers.

With the introduction of Message Routing, OCPI is now better usable for communication via Hubs.

All examples/sequence diagrams in this section use the roles CPO and eMSP as examples, they could be switched, it could be other roles.

4.1.10. No Data Available

There are rare situations, probably use cases not foreseen by the team developing OCPI, where a certain field, that is required, cannot be filled. In such cases, and only in such cases, it is allowed to set a string field to the value: #NA.

For debugging issues, OCPI implementations are required to include unique IDs via HTTP headers in every request/response.

It is advised to use GUID/UUID as values for X-Request-ID and X-Correlation-ID.

As OCPI contains multiple interfaces, different endpoints are available for messaging. The protocol is designed such that the exact URLs of the endpoints can be defined by each party. It also supports an interface per version.

The locations of all the version-specific endpoints can be retrieved by fetching the API information from the versions endpoint. Each version-specific endpoint will then list the available endpoints for that version. It is strongly recommended to insert the protocol version into the URL.

For example: /ocpi/cpo/2.2.1/locations and /ocpi/emsp/2.2.1/locations.

The URLs of the endpoints in this document are descriptive only. The exact URL can be found by fetching the endpoint information from the API info endpoint and looking up the identifier of the endpoint.

During communication over OCPI, one of the communicating parties might be unreachable for an undefined amount of time. OCPI works event-based, new messages and status are pushed from one party to another. When communication is lost, updates cannot be delivered.

OCPI messages SHOULD NOT be queued. When a client does a POST, PUT or PATCH request and that request fails or times out, the client should not queue the message and retry the same message again later.

When the connection is re-established, it is up to the target-server of a connection to GET the current status from the source-server to get back to a synchronized state.

Examples