This repository contains the development for the Service Platform catalogues and repositories. It holds the API implementation of SP catalogue and repos. Moreover, is is closely related to the son-catalogue repository that holds the catalogs of the SDK as well at the son-schema repository that holds the schema for the various descriptors, such as the VNFD and the NSD.
To contribute to the development of the SONATA editor, you may use the very same development workflow as for any other SONATA Github project. That is, you have to fork the repository and create pull requests.
It is recommended to use Ubuntu 14.04.4 LTS (Trusty Tahr).
This code has been run on Ruby 2.1.
A connection to a MongoDB is required, this code has been run using MongoDB version 3.2.1.
Root folder provides a script "installation_mongodb.sh" to install and set up a local MongoDB, or you can use mongoexpress to manage the remote mongo databases.
Ruby gems used (for more details see Gemfile):
- Sinatra - Ruby framework
- puma - Web server
- json - JSON specification
- sinatra-contrib - Sinatra extensions
- rake - Ruby build program with capabilities similar to make
- JSON-schema - JSON schema validator
- Rest-client - HTTP and REST client
- Yard - Documentation generator tool
- mongoid-grid_fs - Implementation of the MongoDB GridFS specification
You may contribute to the editor similar to other SONATA (sub-) projects, i.e. by creating pull requests.
After cloning the source code from the repository, you can run Catalogue-Repositories with the next command:
bundle installWhich will install all the gems needed to run, or if you have docker and docker-compose installed, you can run
docker-compose upThe following shows how to start the API server for the Catalogues-Repositories:
rake startor you can use docker-compose
docker-compose upThe Repositories' API allows the use of CRUD operations to send or retrieve records. The available records include services records (NSR) and functions records (VNFR). For testing the Repositories, you can use 'curl' tool to send a request to the API. It is required to set the HTTP header 'Content-type' field to 'application/json' or 'application/x-yaml' according to your desired format. Remember to set the IP address and port accordingly.
Method GET:
To receive all instances you can use
curl http://localhost:4011/records/nsr curl http://localhost:4011/records/vnfrTo receive an instance by its ID:
curl -X GET http://localhost:4011/records/nsr/9f18bc1b-b18d-483b-88da-a600e9255868curl -X GET http://localhost:4011/records/vnfr/9f18bc1b-b18d-483b-88da-a600e9255016Method POST:
To send a record instance
curl -X POST --data-binary @test_nsr.yaml -H "Content-type:application/x-yaml" http://localhost:4011/records/nsrcurl -X POST --data-binary @test_vnfr.yaml -H "Content-type:application/x-yaml" http://localhost:4011/records/vnfrThe Catalogues' API allows the use of CRUD operations to send, retrieve, update and delete descriptors and sonata files. The available descriptors include services (NSD), functions (VNFD) and packages (PD) descriptors. The Catalogues also support storage for SONATA packages (son-packages), the binary files that contain the descriptors. For testing the Catalogues, you can use 'curl' tool to send a request descriptors to the API. It is required to set the HTTP header 'Content-type' field to 'application/json' or 'application/x-yaml' according to your desired format.
The Catalogues' API now supports API versioning. New API v2 has been introduced in release v2.0 which implements some structure changes in the descriptors. For legacy compatibility, the API v1 is supported, however it is recommended to not mix a MongoDB databse with both versions.
Method GET:
To receive all descriptors you can use
curl http://localhost:4011/catalogues/api/v2/network-servicescurl http://localhost:4011/catalogues/api/v2/vnfscurl http://localhost:4011/catalogues/api/v2/packagesTo receive a descriptor by its ID:
curl http://localhost:4011/catalogues/api/v2/network-services/9f18bc1b-b18d-483b-88da-a600e9255016curl http://localhost:4011/catalogues/api/v2/vnfs/9f18bc1b-b18d-483b-88da-a600e9255017curl http://localhost:4011/catalogues/api/v2/packages/9f18bc1b-b18d-483b-88da-a600e9255018Method POST:
To send a descriptor
curl -X POST --data-binary @nsd_sample.yaml -H "Content-type:application/x-yaml" http://localhost:4011/catalogues/api/v2/network-servicescurl -X POST --data-binary @vnfd_sample.yaml -H "Content-type:application/x-yaml" http://localhost:4011/catalogues/api/v2/vnfscurl -X POST --data-binary @pd_sample.yaml -H "Content-type:application/x-yaml" http://localhost:4011/catalogues/api/v2/packagesMethod PUT:
To update a descriptor is similar to the POST method, but it is required that a older version of the descriptor is stored in the Catalogues
curl -X POST --data-binary @nsd_sample.yaml -H "Content-type:application/x-yaml" http://localhost:4011/catalogues/api/v2/network-servicescurl -X POST --data-binary @vnfd_sample.yaml -H "Content-type:application/x-yaml" http://localhost:4011/catalogues/api/v2/vnfscurl -X POST --data-binary @pd_sample.yaml -H "Content-type:application/x-yaml" http://localhost:4011/catalogues/api/v2/packagesMethod DELETE:
To remove a descriptor by its ID
curl -X DELETE http://localhost:4011/catalogues/network-services/api/v2/9f18bc1b-b18d-483b-88da-a600e9255016curl -X DELETE http://localhost:4011/catalogues/vnfs/api/v2/9f18bc1b-b18d-483b-88da-a600e9255017curl -X DELETE http://localhost:4011/catalogues/packages/api/v2/9f18bc1b-b18d-483b-88da-a600e9255018The API for SONATA packages (son-package) files works very similar to the API for the descriptors or records.
Method GET:
To receive a list of stored packages
curl http://localhost:4011/catalogues/api/v2/son-packagesTo receive a package file
curl http://localhost:4011/catalogues/api/v2/son-packages/9f18bc1b-b18d-483b-88da-a600e9255000Method POST:
To send a package file
HTTP header 'Content-Type' must be set to 'application/zip'
HTTP header 'Content-Disposition' must be set to 'attachment; filename=name_of_the_package'
curl -X POST -H "Content-Type: application/zip" -H "Content-Disposition: attachment; filename=sonata_example.son" -F "@sonata-demo.son" "http://0.0.0.0:4011/catalogues/api/v2/son-packages"Method DELETE:
To remove a package file by its ID
curl -X DELETE http://localhost:4011/catalogues/api/v2/son-packages/9f18bc1b-b18d-483b-88da-a600e9255000For more information about usage of Catalogues, please visit the wikipage link below which contains some information to interact and test the Catalogues API.
- Testing the code - Inside SP Catalogue API Documentation (It currently works for SDK and SP Catalogues)
The Rakefile in root folder includes an specific task to fill the Catalogues with descriptor sample files from sonata-demo package. This is specially useful when starting an empty Catalogue. It can be run with a rake task:
rake init:load_samples[<server>]
Where <server> allows two options: 'development' or sh'integration' server deploymentAn example of usage:
rake init:load_samples[integration]The API documentation is expected to be generated with Swagger soon. Further information can be found on SONATA's wikipages link for SONATA Catalogues:
- SONATA Catalogues - SONATA Catalogues on wikipages
New API documentation in Swagger can be accessed from http://localhost:4011/api-doc while running the Catalogue server
Currently, the API is documented with yardoc and can be built with a rake task:
rake yardFrom here you can use the yard server to browse the docs from the source root:
yard serverAnd they can be viewed from http://localhost:8808/ or you can use docker-compose and view from http://localhost:8808/
The SONATA SDK Catalogue is published under Apache 2.0 license. Please see the LICENSE file for more details.
To support working and testing with the son-catalogue database it is optional to use next tools:
The following lead developers are responsible for this repository and have admin rights. They can, for example, merge pull requests.
- Felipe Vicens (felipevicens)
- Daniel Guija (dang03)
- Santiago Rodriguez (srodriguezOPT)
Please use the GitHub issues and the SONATA development mailing list sonata-dev@lists.atosresearch.eu for feedback.