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 :doc:`vnc_cfg.xsd` schema. The class definitions of all resource types are available at :mod:`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://:/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://:/example_resource/ * *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://:/example_resource/ * *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-' is assumed. * *METHOD*: GET * *URL*: http://:/example_resources?parent_id= *OR* http://:/example_resources?parent_fq_name_str= * *BODY*: None * *RESPONSE*: json list of uuid and href of collection