RAML specifications for Neosperience Metrics Connector and services

nsp_metrics

#%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}