Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
RAML specifications for Neosperience Metrics Connector and services
#%RAML 0.8
#[title] Named Hyperion after the Greek Titan that watches humans from above the sky
title: Hyperion - Metric watcher service
baseUri: http://hyperion.neosperience.com/api/
version: v0.1
#[mediaType] We deal only with JSON formats, for simplicity since it has become the <em>de facto<em> standard for REST resource transfer format
mediaType: application/json
#[protocols] Since this could be sensitive data, we support only HTTPS endpoints, for security reasons
protocols: [HTTPS]
traits:
- searchable:
queryParameters:
limit:
type: string
required: false
description: the maximum number of metrics that should be retrieved from provider
timestamp:
type: date
required: false
description: Retrieves metrics from a specified datetime
tags:
type: string
required: false
description: A comma-separated list of tags to filter metrics
example: |
"myTag01,myTag02"
customFilterQuery:
type: string
required: false
description: An URL-encoded string containing a domain-specific query string. It is used to provide additional filtering for metric data. It will be sent enqueued to query string
example: |
"param01=my%20value&param02=my%20other%20value"
schemas:
#[metric_collection] It is the collection of metrics elements. It has to be thought as an overview of a set of metrcs and is useful for batch updating purposes. Due to this assumpion, only a small set of data is provided by collection items.
- metric_collection : |
{
"$schema":"http://json-schema.org/draft-04/schema#",
"type" : "array",
"items" :
[
{
"type" : "object",
"properties" :
{
"serviceId" : { "type" : "uuid" },
"id" : { "type" : "uuid" },
"timestamp" : { "type" : "timestamp" },
"value" : { "type" : "float" }
}
}
]
}
#[metric] It is the metric resource, projected to be service-independent and can be used to expose data of different types, for different purposes. The service providing a specific metric is a parameter of the returning resource due to the fact that different metrics of the same kind (service) could be listed all at once. ServiceId is part of the unique key identifying a metric; the other part is the id itself. When updating a metric, resources having the same serviceId and id are updated with the new value. Each metric could have also a target value that is used to show progress percentage and provide notification when a goal is matched. Labels and icons are properties of a given metric and can be used for display purposes. Tagging is supported in order to provide flexibility in metrics UIs.
- metric: |
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type" : "object",
"properties" : {
"serviceId" : { "type" : "uuid" },
"serviceLabel": { "type" : "string" },
"serviceIcon": { "type" : "string" },
"id": { "type" : "uuid" },
"label": { "type" : "string" },
"value": { "type" : "float" },
"targetValue": { "type" : "float" },
"timestamp" : { "type" : "date" },
"tags" :
{
"type" : "array",
"items" : { "type" : "string"}
}
},
"required": [ "serviceId", "id", "value" ]
}
resourceTypes:
- metricCollectionType:
securedBy: [basic]
displayName: Collection of metrics
get:
is: [searchable]
description: Retrieves the complete list of metrics available from a given provider
responses:
401:
description: Undauthenticated client
403:
description: Client does not have permissions
200:
description: An array of metrics
body:
application/json:
schema: metric_collection
example: |
[
{
"serviceId" : "a UUID representing the service providing the first metric",
"id" : "a UUID representing the first metric",
"timestamp" : "2015-07-11T08:25:43.511Z",
"value" : 221
},
{
"serviceId" : "another UUID representing the service providing the second metric",
"id" : "a UUID representing a second metric",
"timestamp" : "2015-07-11T18:45:43.511Z",
"value": 42
}
]
- metricResource:
securedBy: [basic]
displayName: A metric
get:
is: [searchable]
description: Retrieves the full information for a given metric
responses:
401:
description: Unauthenticated client
403:
description: Client does not have permissions to access this resource
200:
description: The full metric resource
body:
application/json:
schema: metric
example: |
{
"serviceId" : "a UUID representing the service providing this metric",
"serviceLabel" : "metric Service Display Name",
"serviceIcon" : "http://path/to/service/icon/png",
"id" : "a UUID representing this metric",
"label": "metric display name",
"value": 42,
"timestamp" : "2015-07-11T08:25:43.511Z",
"targetValue": 999
}
securitySchemes:
#[basic] Basic Authentication is the most common method of authentication that can be exposed by a REST service. As stated in RFC2617 it just requires a n Authorization HTTP header with Basic and a token. Usually the token is a Base64 encoding of an username and a password recognized by the system. i.e. "Authorization" : "Basic Base64(<username>:<password>)"
- basic:
type: Basic Authentication
/metric:
type: metricCollectionType
/{serviceId}:
type: metricCollectionType
/{id}:
displayName: A metric representing a value in our metric provider, identified by {id}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment