REST API Details

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.

Discovering API server resources

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"
      }
    }
  ]
}

Creating a resource

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

Reading a 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

Update a 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).

Listing Resources

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.

• METHOD: GET

• URL: http://<ip>:<port>/example_resources?parent_id=<parent_uuid> OR

  http://<ip>:<port>/example_resources?parent_fq_name_str=<parent’s fully-qualified name delimited by ‘:’>

• BODY: None

• RESPONSE: json list of uuid and href of collection