web

README

Annotate takes annotations in a defined schema. The intent is to support multiple backends, but currently only works with elasticsearch.

The fields of an annotation and there suggested ussage are:

• Id: This is a GUID. The GUID is set by the API, so you should only specify it when are changing an existing annotation
• StartDate / EndDate: The start and end date of the annotation. When an annotation is an event without duration, StartDate equals the EndDate. The API can take times in either RFC3339 as referenced in Go's time package or a unix epoch. The two should not be mixed in the same annotation.
• CreationUser: Optional, The username of a human creating the annotation. For machine generated annotations, it is suggested to leave this field blank so the two can be distinguished.
• Url: Optional, An optional link, like http://bosun.org
• Source: Optional, The system that generated the annotation
• Host: Optional, hostname if the host. Recommended convention is all lowercase shortnames
• Owner: Optional, The team or group that the annotation relates to
• Message: Required, free form text

#REST End Points

Create Annotation

Annotations can be created using RFC3339 format or Epoch format (see examples below). The response will be in the same format as the annotation you created. This endpoint has the following behaviors:

• If StartDate and EndDate are not set, the API endpoint will set the time to now
• If StartDate or EndDate (and not both) is set, the endpoint will set the other to be the one that is set. So for single events, you need only specify one or the other
• The Id is a GUID that is set my the API endpoint, and not the user. It gets returned in the response so you can updated the annotation in the future.
• If an Id is set, then the annotation will be updated as long as the GUID exists. Updates require the complete document, as all fields are overwritten (and if the field is missing, an empty value with overwrite what is there). If the GUID is not found, an error will be returned.

URL

/annotation

Method and Request Type

application/json

POST | PUT

URL Params

None

Data Params

Example RFC3339 Format

{
  "Id": "",
  "Message": "test",
  "StartDate": "2016-02-24T22:08:41-05:00",
  "EndDate": "2016-02-24T22:08:41-05:00",
  "CreationUser": "kbrandt",
  "Url": "",
  "Source": "annotate-ui",
  "Host": "",
  "Owner": "sre",
  "Category": "test"
}

Example Epoch Format

{
  "Id": "",
  "Message": "test",
  "StartDate": 1456369836,
  "EndDate": 1456369836,
  "CreationUser": "kbrandt",
  "Url": "",
  "Source": "annotate-ui",
  "Host": "",
  "Owner": "sre",
  "Category": "test"
}

Response

Success:

Code: 200

Example Epoch format

{
  "Id": "78a59f94-76ed-42d2-9ed0-9c7b282c4e83",
  "Message": "test",
  "CreationUser": "kbrandt",
  "Url": "",
  "Source": "annotate-ui",
  "Host": "",
  "Owner": "sre",
  "Category": "test",
  "StartDate": 1456369836,
  "EndDate": 1456369836
}

Failure

Code: 500

Example

{
    "error": "EndDate is before StartDate"}
}

---

Get Annotation

URL

/annotation/:id?Epoch=1

• id is the GUID of the annotation
• Example: annotation/78a59f94-76ed-42d2-9ed0-9c7b282c4e83?Epoch=1

Method and Request Type

application/json

GET

URL Params

Optional

• Epoch=1 makes it so the response has time as Epoch numbers instead of RFC3339 time.

Response

Success:

Code: 200

Example Epoch format

{
  "Id": "78a59f94-76ed-42d2-9ed0-9c7b282c4e83",
  "Message": "test",
  "CreationUser": "kbrandt",
  "Url": "",
  "Source": "annotate-ui",
  "Host": "",
  "Owner": "sre",
  "Category": "test",
  "StartDate": 1456369836,
  "EndDate": 1456369836
}

Failure:

Code: 500

Example

{
    "error":"elastic: Error 404 (Not Found)"
}

---

Update Annotation

This has the same behavior as Create Annotation, but lets you put the id in the url. Whenever updating an annotation, the full annotation gets overwritten. So if you leave a field out, it will be zero'd out.

URL

/annotation/:id

Method and Request Type

application/json

PUT

---

Get Field Values

Get existing unique values for on any of the following fields:

• Source
• Host
• Category
• CreationUser

URL

/annotation/values/:field

• field must be one of the above fields
• example: /annotation/values/Category

Method and Request Type

application/json

GET

Response

Success:

Code: 200

Example

[
  "test",
  "outage"
]

Failure

Code: 500

Example

{
    "error":"invalid field Sizource"
}

---

Query Annotations

Partially Documented - still highly subject to change. But if you provide a StartDate and EndDate, you will get the annotations that were active during the specified window.

URL

/annotation/query

• Example: annotation/query?StartDate=2016-02-23T10:09:13-05:00&EndDate=2016-02-26T10:09:13-05:00

Method and Request Type

application/json

GET

Response

Success:

Code 200

Example

[
  {
    "Id": "2c5ec8f9-3a3e-4d2e-a236-6aa42ef1077b",
    "Message": "test",
    "CreationUser": "kbrandt",
    "Url": "",
    "Source": "annotate-ui",
    "Host": "",
    "Owner": "sre",
    "Category": "outage",
    "StartDate": "2016-02-24T22:10:36-05:00",
    "EndDate": "2016-02-24T22:10:36-05:00"
  },
  {
    "Id": "af83d59b-a6bb-46a6-8d16-ba0e903eab0a",
    "Message": "test",
    "CreationUser": "kbrandt",
    "Url": "",
    "Source": "annotate-ui",
    "Host": "",
    "Owner": "sre",
    "Category": "test",
    "StartDate": "2016-02-24T22:10:36-05:00",
    "EndDate": "2016-02-24T22:10:36-05:00"
  }
]

Error:

Code 500

Example

{
  "error": "couldn't parse EndDate as RFC3339 or epoch: parsing time \"2016-02-a26T10:09:13-05:00\" as \"2006-01-02T15:04:05Z07:00\": cannot parse \"a26T10:09:13-05:00\" as \"02\", strconv.ParseInt: parsing \"2016-02-23T10:09:13-05:00\": invalid syntax"
}

Documentation

Index

• func AddRoutes(router *mux.Router, prefix string, b []backend.Backend, ...) error
• func AddRoutesWithMiddleware(router *mux.Router, prefix string, b []backend.Backend, ...) error
• func DeleteAnnotation(w http.ResponseWriter, req *http.Request)
• func Dir(useLocal bool, name string) http.FileSystem
• func FS(useLocal bool) http.FileSystem
• func FSByte(useLocal bool, name string) ([]byte, error)
• func FSMustByte(useLocal bool, name string) []byte
• func FSMustString(useLocal bool, name string) string
• func FSString(useLocal bool, name string) (string, error)
• func GetAnnotation(w http.ResponseWriter, req *http.Request)
• func GetAnnotations(w http.ResponseWriter, req *http.Request)
• func GetFieldValues(w http.ResponseWriter, req *http.Request)
• func Index(w http.ResponseWriter, r *http.Request)
• func InsertAnnotation(w http.ResponseWriter, req *http.Request)

Functions

func AddRoutes

func AddRoutes(router *mux.Router, prefix string, b []backend.Backend, enableUI, useLocalAssets bool) error

AddRoutes will add annotate routes to the given router, using the specified prefix

func AddRoutesWithMiddleware

func AddRoutesWithMiddleware(router *mux.Router, prefix string, b []backend.Backend, enableUI, useLocalAssets bool, readMiddleware, modifyMiddleware func(http.HandlerFunc) http.Handler) error

AddRoutesWithMiddleware will add annotate routes to the given router, using the specified prefix. It accepts two middleware functions that will be applied to each route, depending on whether they are a "read" operation, or a "write" operation

func DeleteAnnotation

func DeleteAnnotation(w http.ResponseWriter, req *http.Request)

func Dir

func Dir(useLocal bool, name string) http.FileSystem

Dir returns a http.Filesystem for the embedded assets on a given prefix dir. If useLocal is true, the filesystem's contents are instead used.

func FS

func FS(useLocal bool) http.FileSystem

FS returns a http.Filesystem for the embedded assets. If useLocal is true, the filesystem's contents are instead used.

func FSByte

func FSByte(useLocal bool, name string) ([]byte, error)

FSByte returns the named file from the embedded assets. If useLocal is true, the filesystem's contents are instead used.

func FSMustByte

func FSMustByte(useLocal bool, name string) []byte

FSMustByte is the same as FSByte, but panics if name is not present.

func FSMustString

func FSMustString(useLocal bool, name string) string

FSMustString is the string version of FSMustByte.

func FSString

func FSString(useLocal bool, name string) (string, error)

FSString is the string version of FSByte.

func GetAnnotation

func GetAnnotation(w http.ResponseWriter, req *http.Request)

func GetAnnotations

func GetAnnotations(w http.ResponseWriter, req *http.Request)

func GetFieldValues

func GetFieldValues(w http.ResponseWriter, req *http.Request)

func Index

func Index(w http.ResponseWriter, r *http.Request)

func InsertAnnotation

func InsertAnnotation(w http.ResponseWriter, req *http.Request)