Uploaded image for project: 'Bitbucket Cloud'
  1. Bitbucket Cloud
  2. BCLOUD-13957

API examples format is unnecessarily complex and has some field name errors

    XMLWordPrintable

    Details

      Description

      Using the response format of an issue as a reference:

      Many items start with all of: as if anyone would expecting a some of: unless explicitly stated. How does this help readability?

      The first item of objects & sub-objects is an object of type string *, though the real response has no such object, rather it has a normal property called type with a fixed string value. The expected value is not obvious (it's in a low-visibility, grey comment), and may not even be correct (the example mentions an account object but this is reporter in a real response with a type of user).

      Some items show ... instead of the expected contents, like issue->repository->links.

      Some response properties may be null but these are not identified in your examples.

      I understand that you're trying to provide more info about values than a literal example (like listing potential issue priority values) but, at the moment, it's more legible to make a few test requests to see the actual structure of a response.

        Attachments

          Activity

            People

            Assignee:
            Unassigned
            Reporter:
            9bd16972c287 lucas_thereitis
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Dates

              Created:
              Updated: