Graph Annotations

Creating graph annotations

POST /api/v0/graph-annotations

Required permissions for API key

  • Read
  • Write

Input

KEY TYPE DESCRIPTION
title string Annotation title
description string [optional] Annotation details
from number Starting time (epoch seconds)
to number Ending time (epoch seconds)
service string Service name
roles array[string] [optional] Role name array (omit this field to register an annotation related to the service)

Input example

{
  "title": "deploy application",
  "description": "link: https://example.com/",
  "from": 1484000000,
  "to": 1484000030,
  "service": "ExampleService",
  "roles": [ "ExampleRole1", "ExampleRole2" ]
}

Response

The input is returned along with an ID.

Error

STATUS CODE DESCRIPTION
400 When the input is in a format that can’t be received
400 When the title exceeds 250 characters or the description exceeds 1024 characters
400 When the starting time exceeds the ending time
404 When the service and role do not exist
403 When the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Obtaining graph annotations

Specify the service and interval and obtain the graph annotations list. Annotations with intervals intersecting with the specified interval will all be returned.

GET /api/v0/graph-annotations

Required permissions for API key

  • Read

Input (Query parameters)

PARAM TYPE DESCRIPTION
service string Service name
from number the start of the specified interval (epoch seconds)
to number the end of the specified interval (epoch seconds)

Response

{
  "graphAnnotations": [
    {
      "id": "2UdH1QcZQaw",
      "title": "Deploy application",
      "description": "Deploy description",
      "from": 1484020459,
      "to": 1484020759,
      "service": "ExampleService"
    },
    {
      "id": "2UdH1QuiGgj",
      "title": "Release application",
      "description": "Release description",
      "from": 1484021239,
      "to": 1484021239,
      "service": "ExampleService",
      "roles": [ "ExampleRole1", "ExampleRole2" ]
    }
  ]
}

Error

STATUS CODE DESCRIPTION
400 When the necessary query parameters are not specified
404 When the specified service does not exist

Updating graph annotations

PUT /api/v0/graph-annotations/<annotationId>

Required permissions for API key

  • Read
  • Write

Input

The same as Creating graph annotations.

Response

The same as Creating graph annotations, the input is returned with an ID.

Error

STATUS CODE DESCRIPTION
400 When the input is in a format that can’t be received
400 When the title exceeds 250 characters or the description exceeds 1024 characters
400 When the starting time exceeds the ending time
404 When the service or role do not exist
404 When the graph annotation does not exist
403 When the API doesn't have the required permissions / when accessing from outside the permitted IP address range

Deleting graph annotations

DELETE /api/v0/graph-annotations/<annotationId>

Required permissions for API key

  • Read
  • Write

Response

Success

The graph annotation before deletion will be returned.

Error

STATUS CODE DESCRIPTION
404 When the graph annotation does not exist
403 When the API doesn't have the required permissions / when accessing from outside the permitted IP address range