In the REST API everything is referred by namespace and name rather than synthetic IDs. This helps to achieve portability (import / export using JSON).

APIs should allow coarse grain and fine grain access to information in order to control data transfer bandwidth requirements.

Working with Namespaces Basic interaction is:

Get list of namespaces with overview info based on the desired filters. (e.g. key / values for images).
Get objects
Common Response Codes

Create Success: 201 Created
Modify Success: 200 OK
Delete Success: 204 No Content
Failure: 400 Bad Request with details.
Forbidden: 403 Forbidden
Not found: 404 Not found e.g. if specific entity not found
Not found: 405 Not allowed e.g. if trying to delete on a list resource
Not found: 501 Not Implemented e.g. HEAD not implemented
API Version

All URLS will be under the v2 Glance API. If it is not explicitly specified assume /v2/<url>

Create a namespace:
POST /metadefs/namespaces/
Namespace may optionally contain the following in addition to basic fields.

resource_type_associations
properties
objects
tags (future release)
Example Body (with no resource types, properties, objects, or tags):

{
  "namespace": "MyNamespace",
  "display_name": "My User Friendly Namespace",
  "description": "My description",
  "visibility": "public",
  "protected": true
}
Replace a namespace definition (not including properties, objects, or tags):
PUT /metadefs/namespaces/{namespace}
List Namespaces: Returns just the list of namespaces without any objects
properties, or tags.
GET /metadefs/namespaces/
Example Body:

{
    "namespaces": [
        {namespace1Here},
        {namespace2Here}
    ],
    "first": "/v2/metadefs/namespaces?limit=2",
    "next": "/v2/metadefs/namespaces?marker=namespace2Here&limit=2",
    "schema": "/v2/schemas/metadefs/namespaces"
}

With example namespace:

{
    "first": "/v2/metadefs/namespaces?sort_key=created_at&sort_dir=asc",
    "namespaces": [
        {
            "namespace": "OS::Compute::Quota",
            "display_name": "Flavor Quota",
            "description": "Compute drivers may enable quotas on...",
            "visibility": "public",
            "protected": true,
            "owner": "admin",
            "resource_type_associations": [
                {
                    "name": "OS::Nova::Flavor",
                    "created_at": "2014-08-28T17:13:06Z",
                    "updated_at": "2014-08-28T17:13:06Z"
                }
            ],
            "created_at": "2014-08-28T17:13:06Z",
            "updated_at": "2014-08-28T17:13:06Z",
            "self": "/v2/metadefs/namespaces/OS::Compute::Quota",
            "schema": "/v2/schemas/metadefs/namespace"
        },
        {
            "namespace": "OS::Compute::VirtCPUTopology",
            "display_name": "Virtual CPU Topology",
            "description": "This provides the preferred...",
            "visibility": "public",
            "protected": true,
            "owner": "admin",
            "resource_type_associations": [
                {
                    "name": "OS::Glance::Image",
                    "prefix": "hw_",
                    "created_at": "2014-08-28T17:13:06Z",
                    "updated_at": "2014-08-28T17:13:06Z"
                },
                {
                    "name": "OS::Cinder::Volume",
                    "prefix": "hw_",
                    "properties_target": "image",
                    "created_at": "2014-08-28T17:13:06Z",
                    "updated_at": "2014-08-28T17:13:06Z"
                },
                {
                    "name": "OS::Nova::Flavor",
                    "prefix": "hw:",
                    "created_at": "2014-08-28T17:13:06Z",
                    "updated_at": "2014-08-28T17:13:06Z"
                }
            ],
            "created_at": "2014-08-28T17:13:06Z",
            "updated_at": "2014-08-28T17:13:06Z",
            "self": "/v2/metadefs/namespaces/OS::Compute::VirtCPUTopology",
            "schema": "/v2/schemas/metadefs/namespace"
        }
    ],
    "schema": "/v2/schemas/metadefs/namespaces"
}
Filter by adding query parameters:

resource_types = <comma separated list> e.g. OS::Glance::Image
visibility     = Valid values are public, private.
                 Default is to return both public namespaces and private
                 namespaces visible to the user making the request.
limit          = Use to request a specific page size. Expect a response
                 to a limited request to return between zero and limit items.
marker         = Specifies the namespace of the last-seen namespace.
                 The typical pattern of limit and marker is to make an initial
                 limited request and then to use the last namespace from the
                 response as the marker parameter in a subsequent limited
                 request.
Returns specific namespace including metadata definitions (properties,
objects or tags).
GET /metadefs/namespaces/{namespace}
Query parameters:

resource_type  = When specified, the API will look up the prefix associated
                 with the specified resource type and will apply the prefix
                 to all properties (including object properties) prior to
                 returning the namespace. For example, if a
                 resource_type_association in the namespace for
                 OS::Nova::Flavor specifies a prefix of hw:, then all
                 properties in the namespace will be returned with
                 hw:<prop_name>. However if, OS::Glance::Image is specified
                 and the prefix is set to hw_, then the property will be
                 returned as hw_<prop_name>.
Example Body:

{
    "namespace": "MyNamespace",
    "display_name": "My User Friendly Namespace",
    "description": "My description",
    "resource_type_associations" : [
        {
           "name" :"OS::Nova::Aggregate",
           "created_at": "2014-08-28T17:13:06Z",
           "updated_at": "2014-08-28T17:13:06Z"
        },
        {
           "name" : "OS::Nova::Flavor",
           "prefix" : "aggregate_instance_extra_specs:",
           "created_at": "2014-08-28T17:13:06Z",
           "updated_at": "2014-08-28T17:13:06Z"
        }
    ],
    "properties": {
        "nsprop1": {
            "title": "My namespace property1",
            "description": "More info here",
            "type": "boolean",
            "default": true
        }
    },
    "visibility": "public",
    "protected": true,
    "owner": "The Test Owner"
}
Delete a namespace including all content (properties, objects and tags(future release))
DELETE /v2/metadefs/namespaces/{namespace}
List resource types associated with a namespace
GET /v2/metadefs/namespaces/{namespace}/resource_types
Example:

{
  "resource_type_associations": [
      {
          "name": "OS::Glance::Image",
          "prefix": "hw_",
          "created_at": "2014-08-28T17:13:06Z",
          "updated_at": "2014-08-28T17:13:06Z"
      },
      {
          "name": "OS::Cinder::Volume",
          "prefix": "hw_",
          "properties_target": "image_metadata",
          "created_at": "2014-08-28T17:13:06Z",
          "updated_at": "2014-08-28T17:13:06Z"
      },
      {
          "name": "OS::Nova::Flavor",
          "prefix": "hw:",
          "created_at": "2014-08-28T17:13:06Z",
          "updated_at": "2014-08-28T17:13:06Z"
      }
  ]
}
Field descriptions:

name               - (required) Resource type names should be aligned with
                                Heat resource types whenever possible:
                                http://docs.openstack.org/developer/heat/template_guide/openstack.html
prefix             - (optional) Specifies the prefix to use for the given
                                resource type. Any properties in the
                                namespace should be prefixed with this
                                prefix when being applied to the specified
                                resource type. Must include prefix separator
                                (e.g. a colon :).
                                Must include prefix separator (e.g. a colon :).
properties_target  - (optional) Some resource types allow more than one
                                key / value pair per instance.  For example,
                                Cinder allows user and image metadata on
                                volumes. Only the image properties metadata
                                is evaluated by Nova (scheduling or drivers).
                                This property allows a namespace target
                                to remove the ambiguity.
Associate Namespace to resource type
POST /metadefs/namespaces/{namespace}/resource_types
Example:

{
  "name" :"OS::Cinder::Volume",
  "properties_target" : "image_metadata",
  "prefix" : "hw_",
  "created_at": "2014-08-28T17:13:06Z",
  "updated_at": "2014-08-28T17:13:06Z"
}
De-associate Namespace from resource type
DELETE /metadefs/namespaces/{namespace}/resource_types/{resource_type}
Get list of all possible resource types
GET /metadefs/resource_types
Objects

Add Object in a specific namespace:
POST /metadefs/namespaces/{namespace}/objects
Example:

POST /metadefs/namespaces/CompanyXNamespace/objects

{
  "name": "StorageQOS",
  "description": "Our available storage QOS.",
  "required": [
      "minIOPS"
  ],
  "properties": {
      "minIOPS": {
          "type": "integer",
          "description": "The minimum IOPs required",
          "default": 100,
          "minimum": 100,
          "maximum": 30000
      },
      "burstIOPS": {
          "type": "integer",
          "description": "The expected burst IOPs",
          "default": 1000,
          "minimum": 100,
          "maximum": 30000
      }
  }
}
Replace an object definition in a namespace:
PUT /metadefs/namespaces/{namespace}/objects/{object_name}
Delete all objects in specific namespace:
DELETE /metadefs/namespaces/{namespace}/objects
Delete specific object in specific namespace:
DELETE /metadefs/namespaces/{namespace}/objects/{object_name}
Get a specific object in a namespace:
GET /metadefs/namespaces/{namespace}/objects/{object_name}
List objects in a specific namespace:

Return all objects including its schema properties
GET /metadefs/namespaces/{namespace}/objects
Filters by adding query parameters:

limit          = Use to request a specific page size. Expect a response
                 to a limited request to return between zero and limit items.
marker         = Specifies the namespace of the last-seen namespace.
                 The typical pattern of limit and marker is to make an initial
                 limited request and then to use the last namespace from the
                 response as the marker parameter in a subsequent limited
                 request.
Example Body:

{
      "objects": [
      {
          "name": "object1",
          "namespace": "my-namespace",
          "description": "my-description",
          "properties": {
              "prop1": {
                  "title": "My Property",
                  "description": "More info here",
                  "type": "boolean",
                  "default": true
              }
          }
      }
  ],
  "first": "/v2/metadefs/objects?limit=1",
  "next": "/v2/metadefs/objects?marker=object1&limit=1",
  "schema": "/v2/schema/metadefs/objects"
}
Properties (not in an object)

Add Property in a specific namespace:
POST /metadefs/namespaces/{namespace}/properties
Example:

POST /metadefs/namespaces/OS::Compute::Hypervisor/properties

{
      "name": "hypervisor_type",
      "type": "array",
      "description": "The type of hypervisor required",
      "items": {
          "type": "string",
          "enum": ["hyperv", "qemu", "kvm"]
       }
}
Replace a property definition in a namespace:
PUT /metadefs/namespaces/{namespace}/properties/{property_name}
Delete all properties in specific namespace:
DELETE /metadefs/namespaces/{namespace}/properties
Delete Property in specific namespace:
DELETE /metadefs/namespaces/{namespace}/properties/{property_name}
Get a specific property in a namespace:
GET /metadefs/namespaces/{namespace}/properties/{property_name}
List properties in a specific namespace:

Returns details of all properties in a namespace including property schema:
GET /metadefs/namespaces/{namespace}/properties
Filters by adding query parameters:

limit          = Use to request a specific page size. Expect a response
                 to a limited request to return between zero and limit items.
marker         = Specifies the namespace of the last-seen namespace.
                 The typical pattern of limit and marker is to make an initial
                 limited request and then to use the last namespace from the
                 response as the marker parameter in a subsequent limited
                 request.