I am wondering if there’s an official place to report bugs in the Jira v3 REST API. I find the API very instructive and extremely cool, but I think I could pitch for a job with Atlassian…API Documentation QA Engineer. Simple example: some API calls return HTTP 409 when I try to do something a backend DB obviously hates (like try to use the API to submit duplicate data)…okay, makes sense…but not documented at all. Another example…this API refers to “licensed” project types:
Obviously “accessible” and “licensed” are being used synonymously…but you’d think someone would kind of notice that and pick one of those terms…“licensed” seems to be more end-user facing whereas “accessible” seems to be more developer facing. Tons of stuff like this all over the API.
I see that there used to be a link to a site where, in principle, I can submit suggestions (sorry, I’d post the link but I’m only allowed two links per post…you can find it if you search these forums)…but that site won’t let anyone in anymore apparently. At least I can’t get in. Not super complaining here…just want to do my part to be helpful and point out stuff as I encounter it.
Jira’s REST API error codes comply with the set defined by the IETF as part of the RFCs for the HTTP protocol, and since almost every single developer in the world knows how and where to lookup those error codes, like a 409 Conflict code, and what they mean, it would be needlessly redundant for Atlassian to ‘document’ every single possible error code that can be encountered for every single endpoint.
No, they are not.
Once you learn more about how Jira is licenced and how Project permissions are applied, then you’ll know that those two particular words in the API documentation are absolutely are not synonyms.
Certainly I know how to look up these codes. But not every API call returns every possible HTTP response…it’s up to the backend developer to decide which HTTP responses go with which API calls. So it’s kind of weird to document “common” codes, but leave less common codes out especially when those responses would be useful to know. It’s “redundant” to document 403 responses everywhere in the API, but leave 409s out. I mean, either document HTTP responses fully or not at all. A 409 response is certainly possible in an API response, but it’s not “typical”.
Well, I am humble enough (honest!) to be schooled here. If there’s some learning I can do, then a link to some documentation on the difference would be really helpful. But I would ask you…or anyone…to explain to me how the API URL can literally have the term “accessible” in it:
Whereas the description of that very same API only uses the term “license” and never once talks about “accessibility”…quoting the API description:
I mean, it sure seems to me that those terms are being used in a synonymous way from the standpoint of API documentation. I “get” that the words mean different things…but I would argue that from the API documentation’s standpoint, these are differences without any distinction. But I’m happy to read about the distinction…if that’s documented, I’ll gladly read it alongside my humble pie.
But beyond these specific things…I have a list of like…mmm…20, 30 things where I feel the documentation is weirdly inconsistent, or vague, or otherwise problematic for me. I’m super happy to bring these to the attention of the good folks at Atlassian. And maybe those folks can gently chide me and point me to the right places to learn more. But I no longer see that there’s place to bring up API documentation bugs/suggestions and that’s what I’m mostly interested in here.
Another example…this API refers to “licensed” project types: