API JSON schemas URLs are 404

[Hadrien Milano]

I would like to leverage the JSON schemas as seen in the API documentation to write some tooling around the API.

However, the schema URLs lead to 404 Not Found error pages. For instance, this page should be a JSON schema of the issue update request payload, but in fact it does not exist.

[Angélica Luz · Accepted solution]

Hi Hadrien,

The page that you sent is showing 404 for me as well, but on the API documentation there is a scheme for "Edit issue" that is the same as "Issue updated".
Here is the direct link: Edit issue API
Can you please test and let us know if it works for you?

Regards,
Angélica

[Hadrien Milano]

Well that's where I found the faulty URL.

The JSON schema provided for the "edit issue API" contains a URL associated with the key "id". The schema itself should be served when you navigate to this URL, but instead there is a 404 error.

Normally, you can hint IDEs at the schema using its URL. However, in this case it doesn't work because of the 404.

Note that this is the case for all schemas, it is not specific to the "edit issue" api.

[Angélica Luz]

Hi Hadrien,

The URL https://docs.atlassian.com/jira/REST/schema/issue-update for any of other schemas will not return anything.
Have you tried to use the endpoints?
To edit an issue, you won't need the schema, you will need to use PUT /rest/api/2/issue/{issueIdOrKey}.
Please, check the documentation below that has more updated information:
- Jira Cloud platform Developer

Regards,
Angélica

[Hadrien Milano]

> The URL https://docs.atlassian.com/jira/REST/schema/issue-update for any of other schemas will not return anything.

That's exactly the problem. Some text editors can use the schema to provide an enhanced editing experience. Normally, the full JSON schema should be available at that address, and then I can annotate a JSON payload with the `$schema` attribute and that URL to let my editor understand the structure JSON document I am writing.

> Have you tried to use the endpoints?

Yes, that works just fine. There is no problem using the API. I'm just saying that the URL you put in the schema isn't just there for decoration. It should work and it should serve the schema definition.

[Stephen Sifers]

Hello Hadrien,

To summarize what you're asking, You are wanting something along the lines of a Swagger or OpenAPI (externally available Schema) for the entire API for the application. You want to then use this Schema to assist with finding and using API entry URLs within your editor of choice.

With that said, this is currently not an available feature. However, we do have a feature request to make a swagger.json available to use for a similar example you provided. The feature request can be found here: Feature Request.

You also hit upon a good point, the example schema url provided is for example, not actual use. Example: https://docs.atlassian.com/jira/REST/schema. An Actual use would be: https://docs.atlassian.com/jira/REST/7.12.1. The Schema in this example would be the Jira version you were going to access.

Example: https://docs.atlassian.com/jira/REST/schema > WOULD BE > https://docs.atlassian.com/jira/REST/7.12.1

To summarize, you have a great idea and should Vote and Follow the feature request. The Schema listed does require translation for verison (doesn't work when accessing just Schema). If you feel the feature request is not accurate, we would suggest creating a new feature request to match your requirements: Create Feature Request Here

-Stephen Sifers

[Hadrien Milano]

Thanks Stephen, that sums it up pretty well. The schemas and URLs therein tricked me into thinking there was a programmatic schema definition (which I thought to be broken when I realized the links yielded 404s).

I guess swagger would be a good alternative solution.