Skip to content

labels.md

Latest commit

 

History

History
517 lines (382 loc) · 11.1 KB

labels.md

File metadata and controls

517 lines (382 loc) · 11.1 KB
Raw

Labels

Create a label

POST /labels

Code samples

curl -X POST https://localhost:3000/api/v0.9/labels \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Creates a label for the organization.

Payload

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Authentication

This operation requires Basic Auth authentication.

Parameters

Name In Type Required Description
body body LabelRequest true Label payload.

Example responses

201 Response

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.

[
  {
    "status": "error",
    "code": "COMMON_VALIDATION_ERROR",
    "message": "Input validation failed.",
    "errors": [
      {
        "field": "name",
        "message": "name is required."
      }
    ]
  }
]
{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}
{
  "message": "Missing or invalid fields in the request payload"
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status Meaning Description Schema
201 Created The created label. LabelResponse
400 Bad Request Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object. Inline
409 Conflict The request conflicts with an existing resource. ErrorResponse
500 Internal Server Error Internal server error. ErrorResponse

Response Schema

Enumerated Values

Property Value
status error
status error

Response Headers

Status Header Type Format Description
201 Location string uri URL of the created label.

List labels

GET /labels

Code samples

curl -X GET https://localhost:3000/api/v0.9/labels \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Returns all labels configured for the organization.

Authentication

This operation requires Basic Auth authentication.

Example responses

200 Response

{
  "list": [
    {
      "id": "premium",
      "displayName": "Premium APIs"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.

[
  {
    "status": "error",
    "code": "COMMON_VALIDATION_ERROR",
    "message": "Input validation failed.",
    "errors": [
      {
        "field": "name",
        "message": "name is required."
      }
    ]
  }
]
{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}
{
  "message": "Missing or invalid fields in the request payload"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status Meaning Description Schema
200 OK Paginated list of label DTOs. Inline
400 Bad Request Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object. Inline
500 Internal Server Error Internal server error. ErrorResponse

Response Schema

Status Code 200

Name Type Required Restrictions Description
» list [LabelResponse] false none none
»» id string false none The label's handle (unique per org). Not the internal database uuid.
»» displayName string false none none
» pagination Pagination false none Standard pagination metadata returned with collection responses.
»» total integer true none Total number of records matching the query.
»» limit integer true none Maximum number of records returned in this response.
»» offset integer true none Number of records skipped before this page.

Enumerated Values

Property Value
status error
status error

Get a label

GET /labels/{labelId}

Code samples

curl -X GET https://localhost:3000/api/v0.9/labels/{labelId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single label by handle.

Authentication

This operation requires Basic Auth authentication.

Parameters

Name In Type Required Description
labelId path string true The label's handle (its id in request/response payloads), not the internal database uuid.

Example responses

200 Response

{
  "id": "premium",
  "displayName": "Premium APIs"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status Meaning Description Schema
200 OK Label DTO. LabelResponse
404 Not Found Resource not found. ErrorResponse
500 Internal Server Error Internal server error. ErrorResponse

Update a label

PUT /labels/{labelId}

Code samples

curl -X PUT https://localhost:3000/api/v0.9/labels/{labelId} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Updates an existing label by handle.

Payload

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Authentication

This operation requires Basic Auth authentication.

Parameters

Name In Type Required Description
labelId path string true The label's handle (its id in request/response payloads), not the internal database uuid.
body body LabelRequest true Label payload.

Example responses

200 Response

{
  "id": "premium",
  "displayName": "Premium APIs"
}

Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.

[
  {
    "status": "error",
    "code": "COMMON_VALIDATION_ERROR",
    "message": "Input validation failed.",
    "errors": [
      {
        "field": "name",
        "message": "name is required."
      }
    ]
  }
]
{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}
{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status Meaning Description Schema
200 OK Label DTO. LabelResponse
400 Bad Request Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object. Inline
404 Not Found Resource not found. ErrorResponse
409 Conflict The request conflicts with an existing resource. ErrorResponse
500 Internal Server Error Internal server error. ErrorResponse

Response Schema

Enumerated Values

Property Value
status error
status error

Delete a label

DELETE /labels/{labelId}

Code samples

curl -X DELETE https://localhost:3000/api/v0.9/labels/{labelId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Deletes a label by handle.

Authentication

This operation requires Basic Auth authentication.

Parameters

Name In Type Required Description
labelId path string true The label's handle (its id in request/response payloads), not the internal database uuid.

Example responses

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status Meaning Description Schema
204 No Content Label deleted successfully. None
404 Not Found Resource not found. ErrorResponse
500 Internal Server Error Internal server error. ErrorResponse