Copyright (c) 2013-2016 Telefónica Investigación y Desarrollo.
The Policy Manager API (PMI) is a RESTful, resource-oriented API accessed via HTTP/HTTPS that uses JSON-based representations for information interchange that provide functionalities to the Policy Manager GE. This document describes the FIWARE-specific features extension, which allows cloud user to extend the basic functionalities offered by Policy Manager GE in order to cope with policies management.
This specification is the September 2016 release candidate of the PMI API specification corresponding to Release 5.4 of FIWARE. By "release candidate" we mean that only Minor Changes are expected to the API described by this document. In particular, Minor Changes may be of two types:
Extensions to the functionality currently specified by this document. Note that in this case there isn't any risk of breaking backward compatibility on existing software implementations.
Slight modifications in the functionality currently specified by this document, as a consequence of ongoing discussions. Backward compatibility will be taken into account in this case, trying to minimize the impact on existing software implementations. In particular, only completely justified changes impacting backward compatibility will be allowed and "matter of taste" changes will not be allowed.
This specification is licensed under the FIWARE Open Specification License (implicit patents license).
This specification is intended for both software developers and Cloud Providers. For the former, this document provides a full specification of how to interoperate with Cloud Platforms that implements PMI API. For the latter, this specification indicates the interface to be provided in order to create rules with conditions and actions associated the facts received from cloud services. To use this information, the reader should first have a general understanding of the Policy Manager Generic Enabler and also be familiar with:
This specification describes the "full" compliance level.
However, future iterations of this specification might define optionality in some parts and the compliance level (or roles/profiles) corresponding to them.
PMI version 1.0 uses lower camel case (lowerCamelCase) syntax for naming properties and related artifacts used by the API.
The PMI API defines:
Each HTTP request against the PMI requires the inclusion of specific authentication credentials following the same architecture of the other OpenStack projects. The specific implementation of this API supports OAuth v2.0 authentication schemes and will be determined by the specific provider that implements this GE and Interface. To authenticate access to OpenStack services, you must first issue an authentication request with a payload of credentials to OpenStack Identity to get an authentication token.
Credentials are usually a combination of your user name and password, and optionally, the name or ID of the tenant from your FIWARE Lab account. Ask your cloud administrator for your user name (OS_USERNAME), password (OS_PASSWORD), and tenant (OS_PROJECT_NAME) if you do not remember it or sing up your own account in FIWARE Lab account service so that you can generate authentication tokens.
When you send PMI API requests, you include the token in the X-Auth-Token
header. Please,
keep in mind that a token is valid for a limited time before it expires. A token can also
become invalid for other security reasons. The workflow that you have to follow is:
$ curl -s -X POST $OS_AUTH_URL/tokens \
-H "Content-Type: application/json" \
-d '{"auth": {"tenantName": "'"$OS_PROJECT_NAME"'", "passwordCredentials": {"username": "'"$OS_USERNAME"'", "password": "'"$OS_PASSWORD"'"}}}' \
| python -m json.tool
Note: In the FIWARE Lab environment the url of the Identity Management GEi is http://cloud.lab.fi-ware.org:5000/v2.0/
If the request succeeds, it returns the OK (200) response code followed by a response
body that contains a token in the form "id":"token"
and an expiration date and time
in the form "expires":"datetime"
. This is a normal example of the response to the
previous POST, we show only details about the token, the rest are not needed in this case.
{
"access": {
"token": {
"issued_at": "2016-09-02T10:03:51.159419",
"expires": "2016-09-03T10:03:51Z",
"id": "98763040c99h740i95809z2098123704",
"tenant": {
"description": "Joe Foo",
"enabled": true,
"id": "0000000000000098758734z730478503",
"name": "foo"
},
"audit_ids": [
"HsO-r_exQ9upNUMpuf4iWg"
]
},
"serviceCatalog": [ ... ],
"user": { ... },
"metadata": { ... }
}
}
Send API requests and include the token in the X-Auth-Token
header. Continue to
send API requests with that token until the service completes the request or the
Unauthorized (401) error occurs.
If the Unauthorized (401) error occurs, go to the first point and request another token.
The examples in this section use cURL commands. For information about cURL, see http://curl.haxx.se/. For information about the OpenStack APIs, see http://developer.openstack.org/api-ref.html.
The PMI API resources are represented by hypertext that allows each resource to reference other related resources. More concisely, JSON format are used for resource representation and URLs are used for referencing other resources by default. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using either the Accept header with values application/json or adding a .json extension to the request URI. In the following examples we can see the different options in order to represent format.
POST /d3fdddc6324c439780a6fd963a9fa148/servers/15520fa6dc914f97bd1e54f8e1444d41 HTTP/1.1
Host: servers.api.openstack.org
Content-Type: application/json
Accept: application/json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
POST /d3fdddc6324c439780a6fd963a9fa148/servers/15520fa6dc914f97bd1e54f8e1444d41.json HTTP/1.1
Host: servers.api.openstack.org
Content-Type: application/json
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.
The API response payloads in this specification are based on application/json
.
Clients issuing HTTP requests with accept types different than those will get a
406 Not Acceptable
error.
API consumer must indicate the resource identifier while invoking a GET, PUT, POST or DELETE operation. PMI API combines both identification and location by terms of URL. Each invocation provides the URL of the target resource along the verb and any required input data. That URL is used to identify unambiguously the resource. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.
PMI API does not enforce any determined URL pattern to identify its resources. Anyway the PMI API follows the HATEOAS principle (Hypermedia As The Engine Of Application State). This means that resource representation contains the URLs of the related resources (e.g., book representation contains hyperlinks to its chapters; chapter representation contains hyperlinks to its pages...). API consumer obtains the server representation as its following point, which in turn provides hyperlinks that directly or indirectly take to other resources like scalability rules.
Some PMI API entities provide an instance identifier property (instance ID). This property is used to identify unambiguously the entity but not the REST resource used to manage it, which is identified by its URL as described above. It is common that most implementations make use of instance ID to compose the URL (e.g., the book with instance ID 1492 could be represented by resource http://.../book/1492), but such an assumption should not be taken by API consumer to obtain the resource URL from its instance ID.
Last but not least, PMI API does not take care about this instance creation. PMI API supposes that the instance, identified by its serverId, is created in the FIWARE Lab.
Resources often lead to refer to other resources. In those cases, we have to provide an ID or an URL to a remote resource. see OpenStack Compute Developer Guide on their application to infrastructural resources.
Rules are described using JSON, and contain information about CPU and Memory usage, in first instance. The rule is compound of three parts, name, conditions and actions. In this case, the name will be "AlertCPU" and the defined condition expects all server with cpu usage greater than 98.3 and memory load greater or equal to 95.
Actions will create an HTTP POST notification to an url specified on every subscription to this rule. In this case the notification will be that server should be scaled up because CPU usage is greater than certain limit. This is the rule as is expected to:
{
"name": "AlertCPU",
"condition": {
"cpu": {
"value": 98.3,
"operand": "greater"
},
"mem": {
"value": 95,
"operand": "greater equal"
}
},
"action": {
"actionName": "notify-scale",
"operation": "scaleUp"
}
}
Rule conditions represent a boolean condition to be evaluated (e.g. x > 10
).
A rule condition is simply a statement that is either true or false. We can have
two options:
A rule condition is represented by a JSON object with the following syntax:
cpu
, mem
, hdd
, net
. value
property, whose value is a floating number
representing the percentaje of utilization of this metric in the cloud service.operand
property. PMI API v1.0 allows values "greater", "less",
"greater equal", "less equal" for this property.An example of a rule definition can be found in the following code:
"condition": {
"cpu": {
"value": 98.3,
"operand": "greater"
},
"mem": {
"value": 95,
"operand": "greater equal"
}
}
Actions are the messages that we send to the user of the rule when a rule is triggered. An action is represented by a JSON object with the following syntax:
The action id is specified by the object's actionName
property, whose value is
a string containing the action's name. Depending of the actionName
we have predefined
different properties:
If the object's actionName
property has value notify-email
, we have the email and
body which are represented by the object's email
and body
properties, whose values
are the string containing the email address to send the email and the message of this
email. This is a possible example:
"action": {
"actionName": "notify-email",
"email": "foo@fighters",
"body": "You have a problem with your instance, please check it."
}
actionName
property has value notify-scale
, we have action operation.
The action operation is specified by the object's operation
property, whole value is a
string containing the action's operation. PMI API v1.0 allows values "scaleUp", "scaleDown"
for this property. This messages is sent back to the url that is specified in the subscription
process described bellow. This is a possible example:"action": {
"actionName": "notify-scale",
"operation": "scaleUp"
}
actionName
property will have the same
behaviour described in the previous case.Every HTTP request has a status code. 2xx codes signify the PMI API was a success. However, sometimes is not the response that be obtained. All the errors message are sent in JSON format with the following attributes:
message
. A descriptive text of the error that was reported by the PMI API.code
. A integer value to identity the error type.title
. The error type in text format.An example of an error message could be:
{
"error": {
"message": "Expecting to find valid JSON in request body - the server could not comply with the request since it is either malformed or otherwise incorrect. The client is assumed to be in error.",
"code": 400,
"title": "Bad Request"
}
The possible values that we have in the attributes are described bellow. Keep in mind that we give them in the format title
(code
). <description>
:
Bad Request
(400
). The PMI API failed to parse the request as expected. One of
the following errors occurred:
Unauthorized
(401
). One of the following errors occurred:
X-Auth-Token
header is not valid.Forbidden
(403
). The identity was successfully authenticated but it is not authorized
to perform the requested action.
Not Found
(404
). An operation failed because a referenced entity cannot be found by ID.
Service Unavailable
(503
). The Policy Manager is unable to perform the operation due to
it is unavailable. One of the following errors accurred:
Resource related to the context update of facts received from a Orion Publish/Subscribe Context Broker following NGSI-10 specification. It is implemented in the Bosun - Facts subcomponent.
This operation updates the context related to a specific server, identified with its tenantId and serverId. The context information contains the description of the CPU, Memory, Disk and/or Network usages. This message follows the NGSI-10 information model but using JSON format.
Request attributes:
Context element contains different measures. Each measure is an attribute which contains:
name
: The name of the monitored attribute (usedMemPct, cpuLoadPct, netLoadPct,
freeSpacePct).
value
: The value of the attribute.
type
: The type of the value (this component uses string).
In addition there are three more attributes inside the context element:
id
: Subscription unique identifier. Automatically created at creation time in the
Context Broker.
isPattern
: it shows if the query is related to a regular expression for the entity
ID. (false, true)
type
: The type of the context element (this component uses "host").
Finally, Context element is involved into a context response, which also contains:
statusCode
: with the result of the context broker query.Response in JSON:
Succesful operation uses 200 Ok
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the Server to perform action with, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
Resources related to management of Rule besides with global information related to the service.
They are implemented in the Bosun - Cloto subcomponent. All the request to this group requires
the specification of the X-Auth-Token
Header. See "Authentication" subsection for more details.
This operation lists the information of the current version of the API. This operation does not require a request body.
Response in JSON:
Succesful operation uses 200 Ok
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This call updates the window size of the service in order to change the stabilization window size to be applied to the monitoring data received from the Monitoring GE.
Response in JSON:
Succesful operation uses 200 Ok
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation creates a new rule (General Rule) associated to a tenant or project identified by tenantId.
Response in JSON:
Succesful operation uses 200 Ok and the subscription data.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation gets a Genaral Rule associated to a tenant or project identified by tenantId. This operation does not require any request body and the response body is in JSON format.
Response in JSON:
Succesful operation uses 200 Ok and the subscription data.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation allows to update a General Rule condition, the action or both identified by its ruleId of a specific tenant or project identified by its tenantId.
Response in JSON:
Succesful operation uses 200 Ok and the data that was updated.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the rule, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation deletes a specific generic rule identified by its ruleId and associated to a tenant or project identified by its tenantId. It does require neither a request or response body.
Response:
Succesful operation uses 200 Ok with no data.
Errors use a non-2xx and optionally an error payload in JSON format. See subsection "Error Responses" for more details.
Alphanumeric identifier of the rule, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation gets a specific generic rule identified by its ruleId and associated to the tenant or project identified by its tenantId. This operation does not require a request body and the response is in JSON format.
Response in JSON:
Succesful operation uses 200 Ok and the data requested.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the rule, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation returns a list of servers with their rules. There is no body in the request.
Response in JSON:
Succesful operation uses 200 Ok
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation returns the rule or rules list associated with a server identified with its tenantId and serverId. This operation does not require a body and the response is in JSON format.
Response in JSON:
Succesful operation uses 200 Ok
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation creates a new rule or rules associated to a server, which is identified by its serverId and its tenantId. The request specifies the rule to be created and the action associated to it.
Response in JSON:
Succesful operation uses 200 Ok and the identifier of the new rule and the server in which is inserted the new rule.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation allows to update the rule or rules conditions, the action or both or a specific server identified by its serverId and tenantId a specific rule identified by its ruleId. This operation requires a request content and we obtain the response with the updated data.
Response in JSON:
Succesful operation uses 200 Ok and the data that was updated.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the rule, following the OpenStack ID format.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation deletes a specific rule identified by its ruleId, within a server, identified by its serverId and tenantId. This operation does not require a request body.
Response:
Succesful operation uses 200 Ok.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the rule, following the OpenStack ID format.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation gets a specific rule, identified by its ruleId, within a server, identified by its serverId and tenantId. This operation does not require a request body and response body is in JSON format.
Response in JSON:
Succesful operation uses 200 Ok and the rule data.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the rule, following the OpenStack ID format.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation creates a new subcription associated to a rule which is identified by ruleId associated to a server identified by its serverId and tenantId. The request specifies the rule to be activated and the action associated to it.
Response in JSON:
Succesful operation uses 200 Ok and the identifier of the subscription in the Publish/Subscribe Context Broker.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation deletes a subscription, identified by its subscriptionId, within a server, identified by its serverId and tenantId. This operation requires neither a request body or response body. The response is a 200 Ok if it was deleted without any problem or error message in other case.
Response:
Succesful operation uses 200 Ok and no data.
Errors use a non-2xx and optionally an error payload in JSON format. See subsection "Error Responses" for more details.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the subscription, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
This operation gets a subscription, identified by its subscriptionId, within a server, identified by its serverId and tenantId. This operation does not require a request body and response body is in JSON format.
Response in JSON:
Succesful operation uses 200 Ok and the subscription data.
Errors use a non-2xx and optionally an error payload. See subsection "Error Responses" for more details.
Alphanumeric identifier of the server, following the OpenStack ID format.
Alphanumeric identifier of the subscription, following the OpenStack ID format.
Alphanumeric identifier of the Tenant to perform action with, following the OpenStack ID format.
Headers
Content-Type: application/json
Body
{
"contextResponses": [
{
"contextElement": {
"attributes": [
{
"value": "0.12",
"name": "usedMemPct",
"type": "string"
},
{
"value": "0.14",
"name": "cpuLoadPct",
"type": "string"
},
{
"value": "0.856240",
"name": "freeSpacePct",
"type": "string"
},
{
"value": "0.8122",
"name": "netLoadPct",
"type": "string"
}
],
"id": "Trento:193.205.211.69",
"isPattern": "false",
"type": "host"
},
"statusCode": {
"code": "200",
"reasonPhrase": "OK"
}
}
]
}
Headers
Content-Type: application/json
Body
{
"id": 3,
"title": "no error."
}
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
Content-Type: application/json
Body
{
"owner": "TELEFONICA I+D",
"windowsize": <windows_size>,
"version": "<API_version>",
"runningfrom": "<last_launch_date>
"doc": "http://telefonicaid.github.io/fiware-cloto/api/v1.0/"
}
Headers
Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Body
{
"windowsize": <window_size>
}
Headers
Content-Type: application/json
Body
{
"windowsize": <windows_size>
}
Headers
Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>
}
Headers
Content-Type: application/json
Body
{
"ruleId": <RULE_ID>
}
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
Content-Type: application/json
Body
{
"rules": [
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
},
{
"name": <NAME2>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
}
]
}
Headers
Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>
}
Headers
Content-Type: application/json
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>
}
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
Content-Type: application/json
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
}
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
Content-Type: application/json
Body
{
"servers": [
{
"serverId": "<serverId>",
"rules": [
{
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
},
{
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
}
]
},
{
"serverId": "<serverId>",
"rules": [
{
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
},
{
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
}
]
}
]
}
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
Content-Type: application/json
Body
{
"serverId": "<serverId>",
"rules": [
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
},
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
}
]
}
Headers
Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>
}
Headers
Content-Type: application/json
Body
{
"serverId": <serverId>,
"ruleId": <RULE_ID>
}
Headers
Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>
}
Headers
Content-Type: application/json
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>
}
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
Content-Type: application/json
Body
{
"name": <NAME>,
"condition": <CONDITION_DESCRIPTION>,
"action": <ACTION_ON_SERVER>,
"ruleId": "<RULE_ID>"
}
Headers
Content-Type: application/json
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Body
{
"ruleId": <RULE_ID>,
"url": <URL_TO_NOTIFY>,
}
Headers
Content-Type: application/json
Body
{
"subscriptionId": <SUBSCRIPTION_ID>
}
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
X-Auth-Token: 1da5e7629654321e3c123456b89b1cct
Headers
Content-Type: application/json
Body
{
"subscriptionId": <SUBSCRIPTION_ID>,
"url": <URL_TO_NOTIFY>,
"serverId": <SERVER_ID>,
"ruleId": "<RULE_ID>"
}