The configuration API server provides a means of accessing and manipulating configuration elements of the system using HTTP operations on resources represented in JSON. The REST APIs can be classified into two categories:
- those that are configuration element type dependant
- those that are common for all configuration element types
The configuration element types (also referred to as resource types) have a hierarchical relationship described in vnc_cfg.xsd schema. The class definitions of all resource types are available at vnc_cfg_api_server.gen.resource_common module. JSON representation of these objects are what is expected on the wire.
The resources managed by the server can be be obtained at the root URL(home-page).
[root@a5s1 ~]# curl http://10.84.14.1:8082/
{
"href": "http://10.84.14.2:8082",
"links": [
{
"link": {
"href": "http://10.84.14.2:8082/documentation/index.html",
"name": "documentation",
"rel": "documentation"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/config-root",
"name": "config-root",
"rel": "root"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/domains",
"name": "domain",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/service-instances",
"name": "service-instance",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/instance-ips",
"name": "instance-ip",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/network-policys",
"name": "network-policy",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-DNS-records",
"name": "virtual-DNS-record",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/route-targets",
"name": "route-target",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/floating-ips",
"name": "floating-ip",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/floating-ip-pools",
"name": "floating-ip-pool",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/bgp-routers",
"name": "bgp-router",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-routers",
"name": "virtual-router",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/global-system-configs",
"name": "global-system-config",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/namespaces",
"name": "namespace",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/provider-attachments",
"name": "provider-attachment",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-DNSs",
"name": "virtual-DNS",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/customer-attachments",
"name": "customer-attachment",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-machines",
"name": "virtual-machine",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/service-templates",
"name": "service-template",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/security-groups",
"name": "security-group",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/access-control-lists",
"name": "access-control-list",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/network-ipams",
"name": "network-ipam",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-networks",
"name": "virtual-network",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/projects",
"name": "project",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/routing-instances",
"name": "routing-instance",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-machine-interfaces",
"name": "virtual-machine-interface",
"rel": "collection"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/domain",
"name": "domain",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/service-instance",
"name": "service-instance",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/instance-ip",
"name": "instance-ip",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/network-policy",
"name": "network-policy",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-DNS-record",
"name": "virtual-DNS-record",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/route-target",
"name": "route-target",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/floating-ip",
"name": "floating-ip",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/floating-ip-pool",
"name": "floating-ip-pool",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/bgp-router",
"name": "bgp-router",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-router",
"name": "virtual-router",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/config-root",
"name": "config-root",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/global-system-config",
"name": "global-system-config",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/namespace",
"name": "namespace",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/provider-attachment",
"name": "provider-attachment",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-DNS",
"name": "virtual-DNS",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/customer-attachment",
"name": "customer-attachment",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-machine",
"name": "virtual-machine",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/service-template",
"name": "service-template",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/security-group",
"name": "security-group",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/access-control-list",
"name": "access-control-list",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/network-ipam",
"name": "network-ipam",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-network",
"name": "virtual-network",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/project",
"name": "project",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/routing-instance",
"name": "routing-instance",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-machine-interface",
"name": "virtual-machine-interface",
"rel": "resource-base"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/fqname-to-id",
"name": "name-to-id",
"rel": "action"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/id-to-fqname",
"name": "id-to-name",
"rel": "action"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/ifmap-to-id",
"name": "ifmap-to-id",
"rel": "action"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/useragent-kv",
"name": "useragent-keyvalue",
"rel": "action"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-network/%s/ip-alloc",
"name": "virtual-network-ip-alloc",
"rel": "action"
}
},
{
"link": {
"href": "http://10.84.14.2:8082/virtual-network/%s/ip-free",
"name": "virtual-network-ip-free",
"rel": "action"
}
}
]
}
To create a resource, a POST has to be issued on the collection URL. So for a resource of type example-resource,
- METHOD: POST
- URL: http://<ip>:<port>/example_resources/
- BODY: json representation of example-resource type
- RESPONSE: uuid and href of created resource
To read a resource, a GET has to be issued on the resource URL.
- METHOD: GET
- URL: http://<ip>:<port>/example_resource/<example-resource-uuid>
- BODY: None
- RESPONSE: json representation of the resource
To update a resource, a PUT has to be issued on the resource URL.
- METHOD: PUT
- URL: http://<ip>:<port>/example_resource/<example-resource-uuid>
- BODY: json representation of resource attributes that are changing
- RESPONSE: uuid and href of updated resource
References to other resources are specified as a list of dictionaries with “to” and “attr” keys where “to” is the fully-qualified name of the resource being referred to and “attr” is the data associated with the relation (if any).
To list a set of resources, a GET has to be issued on the collection URL with an optional query parameter mentioning the parent resource that contains this collection. If parent resource is not mentioned, a resource named ‘default-<parent-type>’ is assumed.