Problem description
Documentation could be better, and in some cases is incorrect.
For example:
- For the use case actually supported by the API, the documentation is not clear. The POST /retrieve-optimal-edge-cloud-zones returns a list of edge cloud zones that are defined as being "closest" to the device. Are they all equal - pick any and you get the same performance for your application? Or are they ranked, in which case they can't all be the "closest".
- Documentation states "If the mobile subscription cannot be identified from the provided parameters, a
404 NOT_FOUND error is returned", but in fact it would be 404 IDENTIFIER_NOT_FOUND that was returned.
- Documentation states "Should your implementation require the Port value to be passed in addition to the IP-Address, please make that explicit in the documentation, and utilise the GENERIC_400_MISSING_PORT error if the Port header is omitted", but:
- No
IP-Address or Port request headers are defined
- Error
GENERIC_400_MISSING_PORT is not documented as a valid error response for the POST /retrieve-optimal-edge-cloud-zones endpoint
For the Discovery endpoint (POST /retrieve-optimal-edge-cloud-zones):
- It states "You can choose to search without passing any of the inputs parameters or a combination of Application Profile and device information", but
applicationProfileId is a required parameter
edgeCloudRegion looks like a filter parameter, but that doesn't tally with its definition as "the closest Edge Cloud Zone to the device". By definition, there can only be one ECZ that is "closest" to the device, so how is that parameter used. So maybe it overrides what the API thinks is the "closest".- Why is
edgeCloudRegion not a required response parameter, particularly when this is defined as a filter parameter? What does it mean when this parameter is not present for an entry in the response array?
- Are elements in the response array ranked? The documentation does not say.
- What does it mean for the response parameter
edgeCloudZoneStatus to have a default of unknown? Why not mandate this parameter in the response, and force the API provider to say what they mean rather than relying on the default and the API consumer to be aware of this default value.
Some proper examples showing the different responses that each endpoint might provide would be useful.
Expected action
Improve the documentation of the API
Additional context
None
Problem description
Documentation could be better, and in some cases is incorrect.
For example:
404 NOT_FOUNDerror is returned", but in fact it would be404 IDENTIFIER_NOT_FOUNDthat was returned.IP-AddressorPortrequest headers are definedGENERIC_400_MISSING_PORTis not documented as a valid error response for the POST /retrieve-optimal-edge-cloud-zones endpointFor the Discovery endpoint (POST /retrieve-optimal-edge-cloud-zones):
applicationProfileIdis a required parameteredgeCloudRegionlooks like a filter parameter, but that doesn't tally with its definition as "the closest Edge Cloud Zone to the device". By definition, there can only be one ECZ that is "closest" to the device, so how is that parameter used. So maybe it overrides what the API thinks is the "closest".edgeCloudRegionnot a required response parameter, particularly when this is defined as a filter parameter? What does it mean when this parameter is not present for an entry in the response array?edgeCloudZoneStatusto have a default ofunknown? Why not mandate this parameter in the response, and force the API provider to say what they mean rather than relying on the default and the API consumer to be aware of this default value.Some proper examples showing the different responses that each endpoint might provide would be useful.
Expected action
Improve the documentation of the API
Additional context
None