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
- Improve the error message for grammatical unambiguity.
- Update your eRoamingEvseDataPull documentation to specify the actual fields which are incompatible with
LastCall
.
- Update your code snippets to include a request body that won't fail by default
- 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.