Skip to content

API documentation

Jump to bottom
anapolg edited this page Aug 28, 2019 · 5 revisions

The API is an evolution of the API supported in the Sonata-NFV son-cli project.

Requirements

It is necessary a Redis BSD listening in PORT 6379. Some useful Redis server commands:

# installation of redis server
apt-get install redis-server

# redis server listening in port 6379
redis-server --port 6379

# check if redis is active. The message will be 
# PONG if redis is active
redis-cli ping

# stop and start redis
/etc/init.d/redis-server stop
/etc/init.d/redis-server start

Service mode

API overview

A new synchronous feature has been added to the API. With this new feature it is possible to validate an object an receive the validation result in the reply of the HTTP POST request. The descriptor files could be send in three different ways and will be specified in the string query by the argument 'source':

  • local: the descriptor is stored in the local file system. In this case, the location of the descriptor should be specified in the string query by the argument 'path'. Example:
curl -X POST 'http://localhost:5001/api/v1/validations?syntax=true&function=true&source=local&path=file_location_in_system'
  • url: the descriptor is in a URL. This case will be the same than 'local' source. Example:
curl -X POST 'http://localhost:5001/api/v1/validations?syntax=true&function=true&source=local&path=url_where_file_is_located'
  • embedded: the descriptor is included as an attachment in the post request. When the validation is a custom-rules validation, two embedded files will be required, one with the descriptor and other with the rules specification. Example code of embedded request:
url = ("/api/v1/validations?function=true&" +
               "source=embedded&sync=true&integrity=true&" +
               "syntax=true&topology=true&custom=true")
descriptor = open('/home/dani/Documents/firewall-vnfd.yml', 'rb')
rules = open('/home/dani/Documents/custom_rule_1.yml', 'rb')
data = {
        'descriptor': (descriptor.name, descriptor,
                       'application/octet-stream'),
        'rules': (rules.name, rules, 'application/octet-stream')
        }
m = MultipartEncoder(data)
headers = {'Content-Type': m.content_type}
response = self.app.post(url, headers=headers, data=m)

If higher level of validation is required it is necessary to send all the levels in the query stream parameters, i.e.

syntax=true&integrity=true&topology=true

Synchronous queries

In order to get a synchronous result the query string parameter sync=true must be added. This means that if the 200OK reply will contain the result of the validation process. If the sync parameter is not added or is false then the request is processed asynchronously. In any case the validation resource is created so its result can be checked at any moment. Example of synchronous validation request:

{
    "path": "/home/dani/Documents/test_project/test/sources/vnfd/vnfd-sample.yml",
    "type": "function",
    "syntax": true,
    "integrity": true,
    "topology": true,
    "custom": true,
    "resources": {
        "vnfd": {
            "id": "/resources/9b65769c5446a0c3a079ed90c2cdbc95",
            "hashFile": "483630975bc08f88b1aeb3f83299046c"
        },
        "customRules": {
            "id": "/resources/d69874747851bc8310d2cf6c11efd38c",
            "hashFile": "df384c09a265aa19973b9f1d43970ecf"
        }
    },
    "result": {
        "validationId": "/validations/dec11aba80321131d3e7b56c32fe64a5",
        "error_count": 0,
        "warning_count": 0
    }
}

Asynchronous queries

By default all the queries are asynchronous. It means that when a validation resource is created the API will reply inmediatly informaing about the result of the resource creation and the path to reach the validation resource not with the result not the validation itself. The validation result must be accessed later once the validation process has finished. When the validation request is in asynchronous mode the API will return 201OK and the id of the validation. Response example:

(/validations/dec11aba80321131d3e7b56c32fe64a5, 201)

Endpoints

The end-points exposed by the API are as follows:

  • /validations:

    • [POST]: request validation of a descriptor. The type of the descriptor, type of validation... should be specified in the string query of the request.
    • [GET]: return all the validations stored in cache. Returns 404 if there are no validations in the cache.
    • [DELETE]: delete all the validations stored in cache.

  • /validations/string:validationId:

    • [GET]: return the validation (with the id specified by validationID) object stored in the cache. If the validation with id required doesn't exist the API will return 404.
    • [DELETE]: delete the validation (with the id specified by validationID) object from the cache. If the validation with id required doesn't exist the API will return 404.

  • /validations/string:validationId/topology:

    [still working on it]

  • /validations/string:validationId/fwgraphs:

    [still working on it]

  • /resources:

    • [GET]: return all the resources stored in cache. Returns 404 if there are no resources in the cache.
    • [DELETE]: delete all the resources stored in cache.

  • /watchers:

    • [POST]: create new watcher with the parameters in the string query.
    • [GET]: return all the watchers stored in cache. Returns 404 if there are no watchers in the cache.
    • [DELETE]: delete all the watchers stored in cache.
Clone this wiki locally