Difference between revisions of "NearlyDirectApi"

Latest revision as of 23:31, 17 February 2013

• Launchpad Entry: NovaSpec:nearly-direct-api
• Created: 2011-02-18
• Contributors: termie

Summary

This is a proposal for a simple, versatile, easy to understand API that closely follows the underlying implementations and the processes for extending and maintaining it over time.

Please read this through to the end, there will be cake.

It is based on work already completed for the Direct API (previously "EasyApi") and extends it to provide a mechanism for maintaining backwards-compatibility as new features are added.

Features:

• Allows developers to add additional services to Nova without changes to core Nova code.
• Provides a reflection service to list available services, methods and extensions thereof.
• Very easy for client libraries to implement.
• Allows rapid development of Nova while also allowing easy maintaining of backwards compatibility.
• Easy to modify and update as requirements change and optimizations present themselves.
• API documentation can be automatically generated along with the normal documentation.

Specific Goals:

• Versatile enough to support a variety of deployment models with specific examples based on those used by Rackspace and NASA.
• Be open to additional interfaces when applicable.
• Support to-be-determined models for identity and auth.

Specific Non-goals:

• Don't direct the requirements for Swift.

Some future paths that are easily supported by this code:

• Ability to run API endpoints directly associated with individual processes (useful in a queue-less rpc system).
• Adding systems such as rate-limiting, caching, compression, and support for alternate protocols.

Release Note

With this release we've added the first version of the new direction for the OpenStack API. We will maintain backwards compatibility with the existing Rackspace API via its own endpoint, and provide new functionality on a new endpoint.

The new API was designed to be very easy to use and its extension mechanisms will allow us to provide new features at a very fast pace while still allowing us to maintain compatibility and stability through future releases.

Along with this release we're releasing reference API client libraries to help speed up the transition to the new API so new clients can begin taking advantage of new features as soon as they are available.

Rationale

The API is the API

At this point we literally have classes that define the API for individual services such as Compute or Volume and all API implementations besides those based on Direct API are doing significant translations of the inputs and outputs of those implementations.

The full functionality of OpenStack is best expressed by the functionality as designed by the system rather than as by an API designed for a different system and layered on top.

We still retain the ability to limit the methods exposed to the public (or any other endpoint) as well as the ability to provide endpoints specifically supporting backwards compatibility with all released versions.

Being Pythonic is Good

As a project of which the vast majority is Python and whose current popularity abd speed of development can arguably be attributed largely to following those principles by which Python development usually occurs, that this is a "Pythonic" approach has merit on its own.

Backwards Compatibility (and Forward Compatibility) is Possible

One of the success stories of Python and one of the large digressions from the mental models of Java development has been around "duck-typing," the idea that is possible to provide a compatible interface, even to multiple clients who are looking for different interfaces, without the need for strictly versioned interface contracts.

This implementation and proposal follows a moderate line between looseness and strictness, providing a largely free market for core developers and providing a reliable target for client developers, some of whom may very well be core developers on other projects that are part of the same OpenStack system.

By adopting a few simple practices, the vast majority of compatibility related issues can be avoided.

Simpler Data Structures and Code Paths are Better

Long ago a famous programmer wrote that it is better to have 100 functions that operate on one data structure than 10 functions that operate on 10 data structures. Part of the truth of that statement comes from the potential for emergent structure and organic adaptability when building systems based on simple data structures and concepts.

This implementation and proposal provides a very, very simple interface that only requires knowledge of a single style of operation and a single datatype.

User stories

Assumptions

• All required API calls can be modeled under this system.
• Clients will be able to parse JSON easily.

Design

Implementation

UI Changes

Code Changes

Related branch: http://code.launchpad.net/~termie/nova/nearly_direct_api

Migration

Test/Demo Plan

Unresolved issues

BoF agenda and discussion

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.