Bad documentation for /rest/api/3/statuscategory

Jira Development Jira Cloud
,
1

Hello!

I am trying to add a simple status line to my application, as shown in the screenshot.
image

From what I understand, “statusCategories” are hardcoded, and users can’t modify them. Unfortunately, the documentation does not provide this information or a complete list of statusCategories. As a user of the cloud API, this prevents me from binding to them.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflow-status-categories/

There is comprehensive documentation for Jira Server available at StatusCategory (Atlassian JIRA 7.6.1 API).

However, for the cloud version, I’ve encountered the following statuses:

[
    {
        "self": "https://vortex-web-innovations.atlassian.net/rest/api/3/statuscategory/1",
        "id": 1,
        "key": "undefined",
        "colorName": "medium-gray",
        "name": "No Category"
    },
    {
        "self": "https://vortex-web-innovations.atlassian.net/rest/api/3/statuscategory/2",
        "id": 2,
        "key": "new",
        "colorName": "blue-gray",
        "name": "To Do"
    },
    {
        "self": "https://vortex-web-innovations.atlassian.net/rest/api/3/statuscategory/4",
        "id": 4,
        "key": "indeterminate",
        "colorName": "yellow",
        "name": "In Progress"
    },
    {
        "self": "https://vortex-web-innovations.atlassian.net/rest/api/3/statuscategory/3",
        "id": 3,
        "key": "done",
        "colorName": "green",
        "name": "Done"
    }
]

Is this the final list for all?

Please correct the documentation:

  1. Clarify that statusCategories are fixed (if it is true).
  2. Provide a full list of status categories (and correct example responses).
  3. It would be good: explain where to find the complete list of colorName. How can one convert colors like medium-gray and blue-gray to RGB for web usage?

Here https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflow-status-categories/

Good description for server version as example:

image
image584×1052 87.9 KB

Kind regards,
VortexWeb Innovations

1 Like
2

From what I understand, “statusCategories” are hardcoded, and users can’t modify them.

You’ve understood correctly.

Unfortunately, the documentation does not provide this information or a complete list of statusCategories.

The documentation doesn’t need to provide that complete list, that’s the job of the REST API endpoint. Use the endpoint and it will give you the complete list of status categories.

Is this the final list for all?

Yes. It is final. The response from that REST API endpoint is telling you the truth. There are 4 status categories.

Google ‘jira cloud status categories’ you’ll find where the topic has been discussed many, many times before, both here and on other forums. There are 4 status categories for Jira Cloud, the same as Jira Server and Jira Data Center… that’s it and you cannot add more.

If you were to search the Jira Cloud feature requests for ‘status category’, you would have found JRACLOUD-63384 that gives you an even more definitive answer. There are 4 status categories… that’s it, you cannot add more and Atlassian closed the discussion on the topic a decade ago.

1 Like
3

@sunnyape Thank you very much for the explanation! :heart:

For me, a fixed list is great! :partying_face:

But I would like to see all the information from you in the API endpoint description, not to have to search through forums. Documentation is a contract for the development of users’ endpoints.

Also, I see no problem in describing the 4 category options directly in the documentation. Otherwise, in the example, I see an unknown “in-flight”.
image

I wrote a post hoping that representatives from Atlassian will see it and correct the documentation.

Kind regards,
VortexWeb Innovations

2 Likes
4

I understand what you’re saying, but once you go down that path of wishing the REST API’s documentation to provide information about everything, to everyone on all topics as well as complete response examples for all possible scenarios… the documentation would become Encyclopedia Galactica in size and subsequent maintenance!

But, agreed, the documentation is often lacking in basic examples of how to use certain parameters properly and does often contain sample responses that are misleading, so you can’t take it verbatim as being absolutely correct.

5

I’m not claiming “everything” :slightly_smiling_face:

I just want

  1. the addition of one sentence, that the categories are fixed and their list (just 4 values).
  2. In the example - the actual response of the service.

I’m not asking for much)

I gave an example of excellent documentation for the server API.
https://docs.atlassian.com/software/jira/docs/api/7.6.1/com/atlassian/jira/issue/status/category/StatusCategory.html#COMPLETE

Kind regards,
VortexWeb Innovations