Difference between revisions of "Nova/ApiSerializationSpec"

Latest revision as of 23:31, 17 February 2013

• Launchpad Entry: NovaSpec:nova-api-serialization
• Created: April 4, 2011
• Contributors: Mark Washenberger

Summary

The current approach to serialization and deserialization in Nova limits the ability of developers to make changes to requests and responses. This specification proposes a new approach which will make development easier when dealing with serialization and deserialization concerns.

Release Note

The changes associated with this spec should not have any direct end-user impact. However, it should make it possible to address gaps in XML handling in the Openstack API.

Rationale

In the current implementation of Nova, all controllers across the Openstack API depend on a single serializer/deserializer implementation. For most cases all serialization logic is held within this one implementation. This centralization has lead to several problems experienced during the development push for Cactus.

Adding XML namespace to the Openstack API::

 

Adding xmlns attributes to response objects in the Openstack API requires modifying logic in project-level scope.

Differences in XML conventions::

 

There are multiple ways to encode dictionaries and lists in XML. Several of these conventions are used in various places in the Openstack API. The current implementation only supports one type, and modifying it to support a different convention in one resource is complicated and risks introducing bugs into unrelated resources.

JSON changes::

 

The current implementation of JSON serialization is a direct translation to and from python dictionaries. This means that even cosmetic changes to the API specification require changes to controller logic.

Extension attributes::

 

Currently, Openstack API extensions that inject attributes into response objects must handle all serialization and deserialization on their own. This will probably become a source of a lot of duplicated effort.

Request validation::

 

All request validation is left to the controller itself. This clutters controller code and is a potential source of bugs.

Goals

When this specification is implemented, developers should be able to do all of the following.

• Add a new request or response with arbitrary serialized and deserialized forms without having to edit an existing serializer that other parts of the code depend on.
• Write maximally flexible deserialization and controller logic without worrying about accidentally supporting requests with invalid formatting.
• Define extension attributes to an existing response object without rewriting the serialization for that response object.
• Reuse serialization logic where appropriate--without being required to reuse any given serialization logic.

Design

TBD

#!wiki comment/dotted
You can have subsections that better describe specific parts of the issue.

Implementation

TBD

#!wiki comment/dotted
This section should describe a plan of action (the "how") to implement the changes discussed. Could include subsections like:

=== Code Changes ===

Code changes should include an overview of what needs to change, and in some cases even the specific details.

=== Migration ===

Include:
 * data migration, if any
 * redirects from old URLs to new ones, if any
 * how users will be pointed to the new way of doing things, if necessary.

Test/Demo Plan

TBD

#!wiki comment/dotted
This need not be added or completed until the specification is nearing beta.

Unresolved issues

TBD

#!wiki comment/dotted
This should highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved.

BoF agenda and discussion

TBD

#!wiki comment/dotted
Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarising what was discussed and note any options that were rejected.