Questions Regarding the Beacon Format

[ammarbarakat]

@rini21 We are currently working on a validation mechanism for the beacon format on the vp-portal side, aiming to ensure perfect functionality for the portal. However, we have encountered some questions regarding the beacon format and would greatly appreciate your assistance:

1. The "numTotalResult" attribute within the "responseSummary" section does not consistently appear. We wonder if it's possible to make it a required attribute?

2. Within the "meta" section -> "receivedRequestSummary" -> "pagination," we noticed that it is set to 10. Is there a way to modify the pagination in the request? We couldn't find an option for this in the provided documentation.

3. In the "response" section -> "resultSets" -> "resultSet" -> "results" -> "result," we observed an "age" object within another "age" object. Could you clarify if this structure is intentional?

4. If available, we would greatly appreciate it if you could provide the JSON schema for the beaconResponse. Having access to the schema would be helpful for our validation process, as we couldn't find such a schema in the provided documentation.

Thank you in advance for your kind assistance!

[rini21]

Dear @Ammarbr, thank you for bringing up these important points. I'm more than happy to assist you with the following clarifications:

1. Regarding the "numTotalResults" attribute within the "responseSummary" section, it is indeed a required attribute, as clearly stated in the Swagger documentation for both IndividualResponse and CatalogResponse. If you've noticed inconsistencies in its appearance, please provide specific examples to identify the issue and ensure uniformity across implementations.

2. As for the "pagination" attribute within the "meta" section -> "receivedRequestSummary," we deliberately omitted it from this version of Beacon to maintain simplicity in the "meta" section, and hence it requires only apiVersion. If you have come across instances where this attribute is mentioned, kindly point them out to rectify the documentation. Additionally, we value your feedback on whether you believe this attribute should be included in the API specification, and we can discuss it further with the wider group.

3. Regarding the observation of an "age" object within another "age" object in the "response" section -> "resultSets" -> "resultSet" -> "results" -> "result," I would greatly appreciate it if you could share a screenshot or specific examples to better understand the issue. This way, I can investigate the structure and confirm its intention.

4. For your convenience, I've included the links to the JSON schema documentation for the "individuals" endpoint here and the "catalogs" endpoint here. Should you require further assistance or have any additional questions, feel free to let me know.

I hope this response addresses your concerns effectively. Please don't hesitate to reach out if you need any further support. Thank you for your collaboration in ensuring the perfect functionality of the portal!

[ammarbarakat]

Many thanks, @rini21 , for your prompt response!

1. Concerning the "numTotalResults," I've only been able to identify this issue using the Ithaca resource so far. I'm not certain if other resources have the same problem. I've included a screenshot of the request and response for your reference.

2. Personally, I don't currently see a need for the pagination attribute, but I thought it was already in use because it appeared in the response with a default value of 10. You can find it in the first screenshot as well.

3. While attempting to send a GET request to the endpoint, I initially assumed it would provide documentation for the endpoint. However, when I tried to read the content, it didn't seem to be the case. (You can see the "age" object in the screenshot.) Could you please clarify what the exact purpose of the GET request for this endpoint is?

4. Many thanks for sharing the link. This documenation is very helpful

[rini21]

Thank you @ammarbarakat, for your detailed response.

Regarding points 1, 2, and 3: It appears that the issue is not related to the format of this particular flavour of Beacon specification (vp-api-specs) but instead, the Ithaca implementation adheres to the original Beacon specification. I will immediately get in touch with the Ithaca team to inform them that we all should be following the vp-api-specs to ensure consistency and proper implementation.

As for point 4, I'm delighted to hear that you find the provided documentation helpful. If you have any further questions or require additional support, please don't hesitate to reach out.

[rini21]

@ammarbarakat, upon further investigation for point 3, GET is (and was always) never allowed, so kindly refrain from using GET request on /individuals endpoint (as highlighted below):

However, GET requests are allowed for Informational endpoints as described here in the spec. Hope this helps!

[ammarbarakat]

Thanks @rini21 for the help!