API Definition Errors

Steven Cinquegrana

I'm not sure if this is the right place to post this stuff these days, but we've revisited code generation using the JSON SKY API OpenAPI Definition Documents and have found a couple of errors.

1. Gift V2 fails to generate a definition with the errors “Unable to convert message to API definition” and “SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data”. The response doesn't contain a JSON definition, just the error.

2. Query contains an invalid attribute “additionalProperties”: false in the Queries/get section.

Let me know if you need more information.

Alex Wong

@Steven Cinquegrana
Gift v2 is still in preview, so while I do know a bug with adding installment into pledge created via gift v2 api, I can only wait

However, your info is not enough to dive into what problem. It is best you provide exactly what API call you are doing, the HTTP method, URL, query parameter, etc

Steven Cinquegrana

@Alex Wong This isn't about using the APIs or any specific endpoints, it's about the OpenAPI definition documents.

You can see the Gift V2 issue simply by clicking the API definition/Open API link on the Home/API Reference/Gift v2/Endpoint Reference page.

The Query issue is evident when you use an OpenAPI code generator.

I hope that's clearer.

Alex Wong

@Steven Cinquegrana
I see what you mean now.

It is best that you also contact support and report this as a bug for fixing

Daniel Leonard

@Steven Cinquegrana Thank you for reporting these issues. We will look into it and get back to you.

Steven Cinquegrana

@Daniel Leonard Thanks.

Steven Cinquegrana

@Daniel Leonard Just wondering if there was a timeline on these fixes. Thanks, Steve

Daniel Leonard

@Steven Cinquegrana Thank you again for reporting this.

1. Gift V2
   1. We have a support case open with Azure to work through the issue you are experiencing. I can let you know when we have some resolution.
2. Query
   1. This appears to be an issue with v2 of the OpenApi document you are able to download from the existing endpoint reference page. You should be able to download v3 OpenApi documents from the new portal that should validate properly.
      

Steven Cinquegrana

@Daniel Leonard I've tried the new portal pages. Unfortunately, we can't currently use the OpenAPI 3 definition documents as we haven't yet migrated our code generation to use them. We will, though, in due course. In the meantime, having access to validated v2 documents would be preferred.

One thing about these new definition document links: we access them programmatically and have noticed that the URLs require an api-version parameter with a string of the form yyyy-mm-dd{-preview}, eg api-version=2023-05-01-preview. Would it be possible to change this to relax the parameter requirement so that, if omitted, the latest document version is returned? We can examine the returned error to ascertain the latest version if necessary, but this won't be required if there is a default version.

It would also be handy to have a dedicated support page containing links to all of the API definition documents as I'm fairly sure we're not the only ones downloading these programmatically.

Cheers and thanks, Steve

Daniel Leonard

@Steven Cinquegrana
We will continue to work toward getting the Query V2 OpenApi document validating and update you when there is progress. We also appreciate the feedback about programatically retrieving the definition and will work toward a resolution.

Steven Cinquegrana

Hi @Daniel Leonard. It's been a few weeks now, just wondering if you have any news?

Daniel Leonard

@Steven Cinquegrana We are still working toward a resolution for the issue with the Gift V2 API and discussing our options in regard to programatic API definition access without an api-version parameter in the new developer portal. The issue with the Query API has been resolved. Thank you for your patience while we work through these issues.