Skip to content

Latest commit

 

History

History
718 lines (658 loc) · 19.4 KB

labels.md

File metadata and controls

718 lines (658 loc) · 19.4 KB

Labels

A label is a name that classifies an issue. Issues can have zero or more labels. The set of allowed labels is defined per project.

Properties

  • id - Unique and stable global identifier of a label
    • mandatory
    • non editable, auto-assigned
    • type: number
    • example: 1
  • number - Stable identifier of a label relative to a project
    • mandatory
    • non editable, auto-assigned
    • type: number
    • example: 1
  • name - Short name that defines the label. The name is unique per project
    • mandatory
    • editable
    • type: text
    • example: "My Label"
  • project - Name of the project where the label is contained
    • mandatory
    • non editable, auto-assigned
    • type: text
    • example: "My Project"
  • projectId - Id of the project where the label is contained
    • mandatory
    • non editable, auto-assigned
    • type: nuymber
    • example: 1
  • author - Name of the label's creator
    • mandatory
    • non editable, auto-assigned
    • type: text
    • example: "John Doe"
  • authorId - Id of the label's creator
    • mandatory
    • non editable, auto-assigned
    • type: number
    • example: 1

Link Relations

Actions

List Labels

List all project labels, in the order that they were created.

GET /api/projects/{projectId}/labels

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
projectId integer path The project's unique identifier
page integer query Specifies the current page of the list
limit integer query Specifies the number of results per page (max. 100)

Default Response

Status: 200 OK

{
  "class": ["label", "collection"],
  "properties": {
    "collectionSize": 2,
    "pageIndex": 0,
    "pageSize": 2
  },
  "entities": [
    {
      "class": ["label"],
      "rel": ["item"],
      "properties": {
        "id": 1,
        "number": 1,
        "name": "label 1",
        "project": "project 1",
        "projectId": 1,
        "author": "user1",
        "authorId": 1
      },
      "links": [
        {
          "rel": ["self"],
          "href": "/api/projects/1/labels/1"
        },
        {
          "rel": ["project"],
          "href": "/api/projects/1"
        },
        {
          "rel": ["author"],
          "href": "/api/users/1"
        },
        {
          "rel": ["labels"],
          "href": "/api/projects/1/labels"
        }
      ]
    },
    {
      "class": ["label"],
      "rel": ["item"],
      "properties": {
        "id": 2,
        "number": 2,
        "name": "label 2",
        "project": "project 1",
        "projectId": 1,
        "author": "user1",
        "authorId": 1
      },
      "links": [
        {
          "rel": ["self"],
          "href": "/api/projects/1/labels/2"
        },
        {
          "rel": ["project"],
          "href": "/api/projects/1"
        },
        {
          "rel": ["author"],
          "href": "/api/users/1"
        },
        {
          "rel": ["labels"],
          "href": "/api/projects/1/labels"
        }
      ]
    }
  ],
  "actions": [
    {
      "name": "create-label",
      "title": "Create Label",
      "method": "POST",
      "href": "/api/projects/1/labels",
      "type": "application/json",
      "fields": [
        {
          "name": "projectId",
          "type": "hidden",
          "value": 1
        },
        {
          "name": "name",
          "type": "text"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": ["self"],
      "href": "/api/projects/1/labels?page=0&limit=10"
    },
    {
      "rel": ["page"],
      "hrefTemplate": "/api/projects/1/labels{?page,limit}"
    },
    {
      "rel": ["project"],
      "href": "/api/projects/1"
    }
  ]
}

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Resource Not Found

Status: 404 Not Found

Get Label

Get a single project label.

GET /api/projects/{projectId}/labels/{labelNumber}

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
projectId integer path The project's unique identifier
labelNumber integer path The label's identifier relative to the project

Default Response

Status: 200 OK

{
  "class": ["label"],
  "properties": {
    "id": 1,
    "number": 1,
    "name": "label 1",
    "project": "project 1",
    "projectId": 1,
    "author": "user1",
    "authorId": 1
  },
  "actions": [
    {
      "name": "edit-label",
      "title": "Edit Label",
      "method": "PUT",
      "href": "/api/projects/1/labels/1",
      "type": "application/json",
      "fields": [
        {
          "name": "projectId",
          "type": "hidden",
          "value": 1
        },
        {
          "name": "labelNumber",
          "type": "hidden",
          "value": 1
        },
        {
          "name": "name",
          "type": "text"
        }
      ]
    },
    {
      "name": "delete-label",
      "title": "Delete Label",
      "method": "DELETE",
      "href": "/api/projects/1/labels/1",
      "fields": [
        {
          "name": "projectId",
          "type": "hidden",
          "value": 1
        },
        {
          "name": "labelNumber",
          "type": "hidden",
          "value": 1
        }
      ]
    }
  ],
  "links": [
    {
      "rel": ["self"],
      "href": "/api/projects/1/labels/1"
    },
    {
      "rel": ["project"],
      "href": "/api/projects/1"
    },
    {
      "rel": ["author"],
      "href": "/api/users/1"
    },
    {
      "rel": ["labels"],
      "href": "/api/projects/1/labels"
    }
  ]
}

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Resource Not Found

Status: 404 Not Found

Create Label

Create a project label.

POST /api/projects/{projectId}/labels

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
content-type string header Should be set to application/json
projectId integer path The project's unique identifier
name string body Required. Unique (within the project) and short name that defines the label

Default Response

Status: 201 Created
Location: /api/projects/{projectId}/labels/{labelNumber}

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Conflict

Status: 409 Conflict

Edit Label

Edit an already existing project label.

PUT /api/projects/{projectId}/labels/{labelNumber}

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
content-type string header Should be set to application/json
projectId integer path The project's unique identifier
labelNumber integer path The label's identifier relative to the project
name string body Required. Unique and short name that defines the label

Default Response

Status: 200 OK
Location: /api/projects/{projectId}/labels/{labelNumber}

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Resource Not Found

Status: 404 Not Found

Conflict

Status: 409 Conflict

Delete Label

Delete an existing project label.

DELETE /api/projects/{projectId}/labels/{labelNumber}

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
projectId integer path The project's unique identifier
labelNumber integer path The label's identifier relative to the project

Default Response

Status: 200 OK

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Resource Not Found

Status: 404 Not Found

Conflict

Status: 409 Conflict

List Issue Labels

List the issue's current labels, in the order that they were created.

GET /api/projects/{projectId}/issues/{issueNumber}/labels

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
projectId integer path The project's unique identifier
issueNumber integer path The issue's identifier relative to the project
page integer query Specifies the current page of the list
limit integer query Specifies the number of results per page (max. 100)

Default Response

Status: 200 OK

{
  "class": ["label", "collection"],
  "properties": {
    "collectionSize": 2,
    "pageIndex": 0,
    "pageSize": 2
  },
  "entities": [
    {
      "class": ["label"],
      "rel": ["item"],
      "properties": {
        "id": 1,
        "number": 1,
        "name": "label 1",
        "project": "project 1",
        "projectId": 1,
        "author": "user1",
        "authorId": 1
      },
      "actions": [
        {
          "name": "delete-label-from-issue",
          "title": "Delete Label From Issue",
          "method": "DELETE",
          "href": "/api/projects/1/issues/1/labels/1",
          "fields": [
            {
              "name": "projectId",
              "type": "hidden",
              "value": 1
            },
            {
              "name": "issueNumber",
              "type": "hidden",
              "value": 1
            },
            {
              "name": "labelNumber",
              "type": "hidden",
              "value": 1
            }
          ]
        }
      ],
      "links": [
        {
          "rel": ["self"],
          "href": "/api/projects/1/issues/1/labels/1"
        },
        {
          "rel": ["issue"],
          "href": "/api/projects/1/issues/1"
        },
        {
          "rel": ["project"],
          "href": "/api/projects/1"
        },
        {
          "rel": ["author"],
          "href": "/api/users/1"
        },
        {
          "rel": ["labels"],
          "href": "/api/projects/1/issues/1/labels"
        }
      ]
    },
    {
      "class": ["label"],
      "rel": ["item"],
      "properties": {
        "id": 2,
        "number": 2,
        "name": "label 2",
        "project": "project 1",
        "projectId": 1,
        "author": "user1",
        "authorId": 1
      },
      "actions": [
        {
          "name": "delete-label-from-issue",
          "title": "Delete Label From Issue",
          "method": "DELETE",
          "href": "/api/projects/1/issues/1/labels/2",
          "fields": [
            {
              "name": "projectId",
              "type": "hidden",
              "value": 1
            },
            {
              "name": "issueNumber",
              "type": "hidden",
              "value": 1
            },
            {
              "name": "labelNumber",
              "type": "hidden",
              "value": 2
            }
          ]
        }
      ],
      "links": [
        {
          "rel": ["self"],
          "href": "/api/projects/1/issues/1/labels/2"
        },
        {
          "rel": ["issue"],
          "href": "/api/projects/1/issues/1"
        },
        {
          "rel": ["project"],
          "href": "/api/projects/1"
        },
        {
          "rel": ["author"],
          "href": "/api/users/1"
        },
        {
          "rel": ["labels"],
          "href": "/api/projects/1/issues/1/labels"
        }
      ]
    }
  ],
  "actions": [
    {
      "name": "add-label-to-issue",
      "title": "Add Label To Issue",
      "method": "PUT",
      "href": "/api/projects/1/issues/1/labels",
      "type": "application/json",
      "fields": [
        {
          "name": "projectId",
          "type": "hidden",
          "value": 1
        },
        {
          "name": "issueNumber",
          "type": "hidden",
          "value": 1
        },
        {
          "name": "name",
          "type": "text"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": ["self"],
      "href": "/api/projects/1/issues/1/labels?page=0&limit=10"
    },
    {
      "rel": ["page"],
      "hrefTemplate": "/api/projects/1/issues/1/labels{?page,limit}"
    },
    {
      "rel": ["project"],
      "href": "/api/projects/1"
    },
    {
      "rel": ["issue"],
      "href": "/api/projects/1/issues/1"
    }
  ]
}

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Resource Not Found

Status: 404 Not Found

Add Label To Issue

Add a existing label to an issue.

PUT /api/projects/{projectId}/issues/{issueNumber}/labels

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
content-type string header Should be set to application/json
projectId integer path The project's unique identifier
issueNumber integer path The issue's identifier relative to the project
name string body Required. Unique (within the project) and short name that defines the label

Default Response

Status: 201 Created
Location: /api/projects/{projectId}/issues/{issueNumber}/labels

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Resource Not Found

Status: 404 Not Found

Conflict

Status: 409 Conflict

Remove Label From Issue

Remove a existing label from an issue.

DELETE /api/projects/{projectId}/issues/{issueNumber}/labels/{labelNumber}

Parameters

Name Type In Description
accept string header Should be set to either application/json or application/vnd.siren+json
projectId integer path The project's unique identifier
issueNumber integer path The issue's identifier relative to the project
labelNumber integer path The label's identifier relative to the project

Default Response

Status: 200 OK

Bad Request

Status: 400 Bad Request

Requires Authentication

Status: 401 Unauthorized

Resource Not Found

Status: 404 Not Found