yahoo-eng-team team mailing list archive

[Abhishek Kekane <abhishek.kekane@xxxxxxxxxxx>]

Public bug reported:

We are adding support for returning ‘x-openstack-request-id’  to the caller as per the design proposed in cross-project specs:
http://specs.openstack.org/openstack/openstack-specs/specs/return-request-id.html

Problem Description:
Cannot add a new property of list type to the warlock.model object.

The requirement we are trying to meet is to make the request id
available to the user of the client library [3].  The user typically
doesn't have access to the headers, so the request id needs to be part
of the payload returned from each method. In other clients that work
with simple data types, we've subclassed dict, list, etc. to add the
extra property. This adds the request id to the return value without
making a breaking change to the API of the client library.

How is a model object created:
Let’s take an example of glanceclient.api.v2.images.get() call [1]:

Here after getting the response we call model() method. This model()
does the job of creating a warlock.model object(essentially a dict)
based on the schema given as argument (image schema retrieved from
glance in this case). Inside model() the raw() method simply return the
image schema as JSON object. The advantage of this warlock.model object
over a simple dict is that it validates any changes to object based on
the rules specified in the reference schema.  The keys of this  model
object are available as object properties to the caller.

Underlying reason:
The schema for different sub APIs is returned a bit differently. For images, metadef APIs glance.schema.Schema.raw() is used which returns a schema containing “additionalProperties”: {“type”: “string”}. Whereas for members and tasks APIs glance.schema.Schema.minimal() is used to return schema object which does not contain “additionalProperties”.

So we can add extra properties of any type to the model object returned
from members or tasks API but for images and metadef APIs we can only
add properties which can be of type string. Also for the latter case we
depend on the glance configuration to allow additional properties.

As per our analysis we have come up with two approaches for resolving
this issue:

Approach #1:  Inject request_ids property in the warlock model object in glance client
Here we do the following:
1. Inject the ‘request_ids’ as additional property into the model object(returned from model())
2. Return the model object which now contains request_ids property

Limitations:
1. Because the glance schemas for images and metadef only allows additional properties of type string, so even though natural type of request_ids should be list we have to make it as a comma separated ‘string’ of request ids as a compromise.
2. Lot of extra code is needed to wrap objects returned from the client API so that the caller can get request ids. For example we need to write wrapper classes for dict, list, str, tuple, generator.
3. Not a good design as we are adding a property which should actually be a base property but added as additional property as a compromise.
4. There is a dependency on glance whether to allow custom/additional properties or not. [2]

Approach #2:  Add ‘request_ids’ property to all schema definitions in
glance

Here we add  ‘request_ids’ property as follows to the various APIs
(schema):

“request_ids”: {
  "type": "array",
  "items": {
    "type": "string"
  }
}

Doing this will make changes in glance client very simple as compared to approach#1.
This also looks a better design as it will be consistent.
We simply need to modify the request_ids property in  various API calls for example glanceclient.v2.images.get().

[1] https://github.com/openstack/python-glanceclient/blob/master/glanceclient/v2/images.py#L179
[2] https://github.com/openstack/glance/blob/master/glance/api/v2/images.py#L944
[3] http://specs.openstack.org/openstack/openstack-specs/specs/return-request-id.html

** Affects: glance
     Importance: Wishlist
     Assignee: Abhishek Kekane (abhishek-kekane)
         Status: New


** Tags: lite-spec

-- 
You received this bug notification because you are a member of Yahoo!
Engineering Team, which is subscribed to Glance.
https://bugs.launchpad.net/bugs/1525259

Title:
  Add request_ids attribute to v2 schemas

Status in Glance:
  New

Bug description:
  We are adding support for returning ‘x-openstack-request-id’  to the caller as per the design proposed in cross-project specs:
  http://specs.openstack.org/openstack/openstack-specs/specs/return-request-id.html

  Problem Description:
  Cannot add a new property of list type to the warlock.model object.

  The requirement we are trying to meet is to make the request id
  available to the user of the client library [3].  The user typically
  doesn't have access to the headers, so the request id needs to be part
  of the payload returned from each method. In other clients that work
  with simple data types, we've subclassed dict, list, etc. to add the
  extra property. This adds the request id to the return value without
  making a breaking change to the API of the client library.

  How is a model object created:
  Let’s take an example of glanceclient.api.v2.images.get() call [1]:

  Here after getting the response we call model() method. This model()
  does the job of creating a warlock.model object(essentially a dict)
  based on the schema given as argument (image schema retrieved from
  glance in this case). Inside model() the raw() method simply return
  the image schema as JSON object. The advantage of this warlock.model
  object over a simple dict is that it validates any changes to object
  based on the rules specified in the reference schema.  The keys of
  this  model object are available as object properties to the caller.

  Underlying reason:
  The schema for different sub APIs is returned a bit differently. For images, metadef APIs glance.schema.Schema.raw() is used which returns a schema containing “additionalProperties”: {“type”: “string”}. Whereas for members and tasks APIs glance.schema.Schema.minimal() is used to return schema object which does not contain “additionalProperties”.

  So we can add extra properties of any type to the model object
  returned from members or tasks API but for images and metadef APIs we
  can only add properties which can be of type string. Also for the
  latter case we depend on the glance configuration to allow additional
  properties.

  As per our analysis we have come up with two approaches for resolving
  this issue:

  Approach #1:  Inject request_ids property in the warlock model object in glance client
  Here we do the following:
  1. Inject the ‘request_ids’ as additional property into the model object(returned from model())
  2. Return the model object which now contains request_ids property

  Limitations:
  1. Because the glance schemas for images and metadef only allows additional properties of type string, so even though natural type of request_ids should be list we have to make it as a comma separated ‘string’ of request ids as a compromise.
  2. Lot of extra code is needed to wrap objects returned from the client API so that the caller can get request ids. For example we need to write wrapper classes for dict, list, str, tuple, generator.
  3. Not a good design as we are adding a property which should actually be a base property but added as additional property as a compromise.
  4. There is a dependency on glance whether to allow custom/additional properties or not. [2]

  Approach #2:  Add ‘request_ids’ property to all schema definitions in
  glance

  Here we add  ‘request_ids’ property as follows to the various APIs
  (schema):

  “request_ids”: {
    "type": "array",
    "items": {
      "type": "string"
    }
  }

  Doing this will make changes in glance client very simple as compared to approach#1.
  This also looks a better design as it will be consistent.
  We simply need to modify the request_ids property in  various API calls for example glanceclient.v2.images.get().

  [1] https://github.com/openstack/python-glanceclient/blob/master/glanceclient/v2/images.py#L179
  [2] https://github.com/openstack/glance/blob/master/glance/api/v2/images.py#L944
  [3] http://specs.openstack.org/openstack/openstack-specs/specs/return-request-id.html

To manage notifications about this bug go to:
https://bugs.launchpad.net/glance/+bug/1525259/+subscriptions