Uploaded image for project: 'Jira Server and Data Center'
  1. Jira Server and Data Center
  2. JRASERVER-65654

Improve the response schema in our REST API documentation

    XMLWordPrintable

    Details

    • Support reference count:
      1
    • Feedback Policy:
      We collect Jira feedback from various sources, and we evaluate what we've collected when planning our product roadmap. To understand how this piece of feedback will be reviewed, see our Implementation of New Features Policy.

      Description

      Summary

      Our REST API documentation (https://docs.atlassian.com/jira/REST/server/) does provide the schema of the response, but it can be improved to give more information of the response.

      For example, the Get Issue has the following response schema

      {
          "id": "https://docs.atlassian.com/jira/REST/schema/issue#",
          "title": "Issue",
          "type": "object",
          "properties": {
              "expand": {
                  "type": "string"
              },
              "id": {
                  "type": "string"
              },
              "self": {
                  "type": "string",
                  "format": "uri"
              },
              "key": {
                  "type": "string"
              },
              "fields": {
                  "type": "object",
                  "patternProperties": {
                      ".+": {}
                  },
                  "additionalProperties": false
              },
              ...
              ...
              ...
          }
      }

      This basically means that 'fields' can have any kind of property with any name, which isn't very useful.

      Suggestion

      Improve the documentation to include more details such as what fields could be returned along with the types and properties, at least for system fields which would always be returned.

      The same should be applied for all other response schema. If there are any items which would always be returned, include those in the documentation

        Attachments

          Activity

            People

            Assignee:
            mpaisley Mel Paisley
            Reporter:
            ywoo Yit Wei Woo
            Votes:
            26 Vote for this issue
            Watchers:
            8 Start watching this issue

              Dates

              Created:
              Updated: