Swagger V3 General concepts

In Swagger V3 we've had some general reconciliations, this page will help you understand the basic concept changes we've made during the upgrade

Reference based listings

Instead of listing the fully populated models we provide model references which can be directly used for other endpoints. For example: You can now list all the user references and use the same model to set an assignee of a tracker item.

For example, via listing all tracker items in a tracker you will return a page of references:

{
  "page": 1,
  "pageSize": 25,
  "total": 5,
  "itemRefs": [
    {
      "id": 1129,
      "name": "Variants Management software",
      "type": "TrackerItemReference"
    },
    {
      "id": 1055,
      "name": "Define Test Cases",
      "type": "TrackerItemReference"
    },
    {
      "id": 1054,
      "name": "Variants Management software",
      "type": "TrackerItemReference"
    },
    {
      "id": 1053,
      "name": "Bluetooth",
      "type": "TrackerItemReference"
    },
    {
      "id": 1052,
      "name": "USB",
      "type": "TrackerItemReference"
    }
  ]
}

Via listing all tracker permissions:

[
  {
    "role": {
      "id": 1,
      "name": "Project Admin",
      "type": "RoleReference"
    },
    "trackerPermissions": [
      {
        "id": 0,
        "name": "issue_view_not_own",
        "type": "TrackerPermissionReference"
      },
      {
        "id": 1,
        "name": "issue_edit_not_own",
        "type": "TrackerPermissionReference"
      },
      {
        "id": 2,
        "name": "issue_view",
        "type": "TrackerPermissionReference"
      },
...

For multiple item queries you can still use some specific endpoints like: GET /v3/reports/{reportId}/items

Usage of references instead of ids

As the product of the reference based listings, we have used these reference objects to refer entities in the system. This will include the usability and readability of the API.

For example instead of providing list of permission ids for a specific role in a tracker, you'll need to use references (which are the same objects coming back from the GET calls):

{
  "permissions": [
      {
        "id": 0,
        "name": "issue_view_not_own",
        "type": "TrackerPermissionReference"
      },
      {
        "id": 1,
        "name": "issue_edit_not_own",
        "type": "TrackerPermissionReference"
      },
      {
        "id": 2,
        "name": "issue_view",
        "type": "TrackerPermissionReference"
      }
  ]
}