OICP-2.3 eRoamingPullEvseData: "delta pull" / "LastCall" - Documentation Incomplete and Inconsistent

[weigert]

Problem Description:

When trying to implement eRoamingPullEvseData with "delta pull", i.e. with request-body "LastCall" specified, the documentation is only marginally helpful and the information is actually incomplete and inconsistent.

Sources:
Code Snippets
Old / Deprecated Swagger Spec
OICP-2.3 Documentation

Expected Behavior: Regular eRoamPullEvseData Call

A regular eRoamPullEvseData call can be tested with curl as follows:

curl -X POST 'https://service-qa.hubject.com/api/oicp/evsepull/v23/providers/ProviderID/data-records' \
     -H 'Content-Type: application/json' \
     -d \
'{
  "GeoCoordinatesResponseFormat": "Google",
  "IsHubjectCompatible": true,
  "ProviderID": "ProviderID"
}' \
     --cert    ./hubject-client-cert.pem \
     --key     ./hubject-client-key.pem \
     --verbose --insecure

This call succeeds as expected and returns a full EvseDataPull with no issues. Pagination functions as expected and other parameters can be passed.

Unexpected Behavior: eRoamPullEvseData Delta Pull Call

Next, we wish to implement a "delta pull" by adding the LastCall property to our JSON request body (we can generate an ISO-8601 timestamp using e.g. date -Iseconds on MacOS). According to the documentation, we expect the following call to succeed:

curl -X POST 'https://service-qa.hubject.com/api/oicp/evsepull/v23/providers/ProviderID/data-records' \
     -H 'Content-Type: application/json' \
     -d \
'{
  "GeoCoordinatesResponseFormat": "Google",
  "IsHubjectCompatible": true,
  "LastCall": "2021-10-10T10:00:00.000Z",
  "ProviderID": "ProviderID"
}' \
     --cert    ./hubject-client-cert.pem \
     --key     ./hubject-client-key.pem \
     --verbose --insecure

but executing this call will return the following error message:

{"message":"Error parsing/validating JSON. Object errors: ERoamingPullEvseData23: LastCall and other AuthenticationModes, OperatorIDs, CountryCodes, Accessibility, RenewableEnergy, IsHubjectCompatible, IsOpen24Hours, RenewableEnergy, CalibrationLawDataAvailability fields can not be provided"}

This error message states that LastCall is incompatible with a large number of fields. These incompatibilities are NOT described in the OICP-2.3 documentation. In the particular curl above, the property IsHubjectCompatible must be removed in order for the call to succeed.

Additionally, the code-snippets provided are not useful for actual functioning calls and instead only help give a precise definition of data formats.

In effect, the intended implementation is hidden from the API implementer unless they figure out what the error message is trying to say. This is inconsistent with the documentation all across this OICP-2.3 repository.

The provided error message is uninformative because of English grammar. Reading it regularly implies that none of the listed fields (from LastCall to CalibrationLawDataAvailability) are allowed in the call, especially because of no indication in the documentation about what it is actually trying to say (that LastCall is incompatible with more fields than indicated).

What the error message intends to say is:

"Error validating JSON. Object errors: ERoamingPullEvseData23: LastCall can not be provided with fields AuthenticationModes, OperatorIDs, CountryCodes, Accessibility, RenewableEnergy, IsHubjectCompatible, IsOpen24Hours, RenewableEnergy, CalibrationLawDataAvailability - incompatible.

Finally, the old swagger documentation is also incorrect because it states that a large number of fields are required, whereas they are not.

The Correct Call

For anybody reading this issue in the future, here is a functioning test curl delta pull for eRoamingEvseDataPull:

curl -X POST 'https://service-qa.hubject.com/api/oicp/evsepull/v23/providers/ProviderID/data-records' \
     -H 'Content-Type: application/json' \
     -d \
'{
  "GeoCoordinatesResponseFormat": "Google",
  "LastCall": "2021-10-10T10:00:00.000Z",
  "ProviderID": "ProviderID"
}' \
     --cert    ./hubject-client-cert.pem \
     --key     ./hubject-client-key.pem \
     --verbose --insecure

Proposed Fixes

1. Improve the error message for grammatical unambiguity.
2. Update your eRoamingEvseDataPull documentation to specify the actual fields which are incompatible with LastCall.
3. Update your code snippets to include a request body that won't fail by default
4. Update your swagger docs to have a correct spec

I acknowledge that you have deprecated the swagger documentation - nevertheless this or a correctly defined code snippets doc would be a useful resource for developers trying to implement this.

[st4rtr3ck]

+1 for this.