Metadata

Metadata

With this API, you can register arbitrary JSON data to hosts, services, and roles. You can use it to register a variety of information such as the management ID and/or other data to help you manage efficiently.

The namespace is used as an identifier for the metadata. We recommend using a consistent identifier such as project or environment. The endpoint of retrieving, creating, updating, and deleting metadata are consistent having the following URL.

/api/v0/hosts/<hostId>/metadata/<namespace>

You can obtain and register JSON (object, array, string, number, boolean, null) to this endpoint.

{
  "type": 12345,
  "region": "jp",
  "env": "staging",
  "instance_type": "c4.xlarge"
}

Numeric characters,_, and - can be used with letters of the alphabet ([-a-zA-Z0-9_]+). However, a namespace that begins with mackerel will be used by the Mackerel system.

Get Host Metadata

Obtain registered metadata.

GET /api/v0/hosts/<hostId>/metadata/<namespace>

Required permissions for the API key

  • Read

Response

JSON of the registered data is returned. The date and time of metadata’s last update is configured in the response header’s Last-Modified.

Error
STATUS CODE DESCRIPTION
400 when more than a week has passed since the host retired
404 when the host does not exist
404 when the specified metadata does not exist for the host

Register/Update Host Metadata

Create and update arbitrary JSON as metadata of the host.

PUT /api/v0/hosts/<hostId>/metadata/<namespace>

Required permissions for the API key

  • Read
  • Write

Input

Any JSON can be specified. However, the size of the data is limited to 100KB.

Response

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
400 when the host has already been retired
400 when the namespace has an invalid value
400 when metadata limit (50 per 1 host) has been exceeded and you try to register
404 when the host does not exist
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range
413 when the metadata exceeds 100KB

Delete Host Metadata

DELETE /api/v0/hosts/<hostId>/metadata/<namespace>

Required permissions for the API key

  • Read
  • Write

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
400 when the host has already been retired
404 when the host does not exist
404 when the specified metadata does not exist for the host
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range

List Host Metadata

GET /api/v0/hosts/<hostId>/metadata

Required permissions for the API key

  • Read

Response

Success

{
  "metadata": [<metadata>, <metadata>, ...]
}

<metadata>: an object that holds the following keys.

KEY TYPE DESCRIPTION
namespace string The namespace of each metadata

Error

STATUS CODE DESCRIPTION
400 when more than a week has passed since the host retired
404 when the host does not exist

Get Service Metadata

Obtain registered metadata.

GET /api/v0/services/<serviceName>/metadata/<namespace>

Required permissions for the API key

  • Read

Response

JSON of the registered data is returned. The date and time of metadata’s last update is configured in the response header’s Last-Modified.

Error
STATUS CODE DESCRIPTION
404 when the service does not exist
404 when metadata specified for the service does not exist

Register/Update Service Metadata

Create and update arbitrary JSON as metadata of the service.

PUT /api/v0/services/<serviceName>/metadata/<namespace>

Required permissions for the API key

  • Read
  • Write

Input

Any JSON can be specified. However, the size of the data is limited to 100KB.

Response

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
400 when the namespace is invalid
400 when trying to register while exceeding the limit of metadata per service (50 per service)
404 when the service does not exist
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range
413 when metadata exceeds 100 KB

Delete Service Metadata

DELETE /api/v0/services/<serviceName>/metadata/<namespace>

Required permissions for the API key

  • Read
  • Write

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
404 when the service does not exist
404 when metadata specified for the service does not exist
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range

List Service Metadata

GET /api/v0/services/<serviceName>/metadata

Required permissions for the API key

  • Read

Response

Success

{
  "metadata": [<metadata>, <metadata>, ...]
}

<metadata>: an object that contains the following keys

KEY TYPE DESCRIPTION
namespace string namespace

Error

STATUS CODE DESCRIPTION
404 when the service does not exist

Get Role Metadata

Obtain registered metadata.

GET /api/v0/services/<serviceName>/roles/<roleName>/metadata/<namespace>

Required permissions for the API key

  • Read

Response

JSON of the registered data is returned. The date and time of metadata’s last update is configured in the response header’s Last-Modified.

Error
STATUS CODE DESCRIPTION
404 when the service/role does not exist
404 when the metadata specified for the role does not exist

Register/Update Role Metadata

Create and update arbitrary JSON as metadata of the role.

PUT /api/v0/services/<serviceName>/roles/<roleName>/metadata/<namespace>

Required permissions for the API key

  • Read
  • Write

Input

Any JSON can be specified. However, the size of the data is limited to 100KB.

Response

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
400 when the namespace is invalid
400 when trying to register and exceeding the limit of metadata per role (10 per role)
404 when the service/role does not exist
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range
413 when metadata exceeds 100 KB

Delete Role Metadata

DELETE /api/v0/services/<serviceName>/roles/<roleName>/metadata/<namespace>

Required permissions for the API key

  • Read
  • Write

Response

Success

{
  "success": true
}

Error

STATUS CODE DESCRIPTION
404 when the service/role does not exist
404 when the metadata specified for the role does not exist
403 when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range

List Role Metadata

GET /api/v0/services/<serviceName>/roles/<roleName>/metadata

Required permissions for the API key

  • Read

Response

Success

{
  "metadata": [<metadata>, <metadata>, ...]
}

<metadata>: an object that contains the following keys

KEY TYPE DESCRIPTION
namespace string namespace

Error

STATUS CODE DESCRIPTION
404 when the service/role does not exist