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.

Getting 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

Registering/Updating 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

Deleting 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

Listing 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

Getting 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

Registering/Updating 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

Deleting 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

Listing 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

Getting 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

Registering/Updating 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

Deleting 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

Listing 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