This change renames the service api modules to be organized under the sahara.service.api package. A v2 package has been added which holds the equivalent v10 and v11 functions. To make the api version setup transparent to the caller, the global OPS variable has been refactored into the base sahara.service.api package. Changes * create sahara/service/api package * rename sahara/service/api.py to sahara/service/api/v10.py * rename sahara/service/edp/api.py to sahara/service/api/v11.py * correct occurances of old imports in code and tests * rename sahara/tests/unit/service/test_api.py to sahara/tests/unit/service/api/test_v10.py * add initial v2 equivalents for current api services * move global OPS object into the sahara.service.api package * add documentation for the api service layer Partial-Implements: bp v2-api-experimental-impl Depends-On: I16918a30a862b42edd7a982caf555be618199ac3 Change-Id: Iefbedbc76ac620ff012bcaf536c17637b6252a15
4.2 KiB
API Version 2 Development
The sahara project is currently in the process of creating a new RESTful application programming interface (API). This interface is experimental and will not be enabled until it has achieved feature parity with the current (version 1.1) API.
This document defines the steps necessary to enable and communicate with the new API. This API has a few fundamental changes from the previous APIs and they should be noted before proceeding with development work.
Warning
This API is currently marked as experimental. It is not supported by the sahara python client. These instructions are included purely for developers who wish to help participate in the development effort.
Enabling the experimental API
There are a few changes to the WSGI pipeline that must be made to enable the new v2 API. These changes will leave the 1.0 and 1.1 API versions in place and will not adjust their communication parameters.
To begin, uncomment, or add, the following sections in your api-paste.ini file:
[app:sahara_apiv2]
paste.app_factory = sahara.api.middleware.sahara_middleware:RouterV2.factory
[filter:auth_validator_v2]
paste.filter_factory = sahara.api.middleware.auth_valid:AuthValidatorV2.factory
These lines define a new authentication filter for the v2 API, and define the application that will handle the new calls.
With these new entries in the paste configuration, we can now enable them with the following changes to the api-paste.ini file:
[pipeline:sahara]
pipeline = cors request_id acl auth_validator_v2 sahara_api
[composite:sahara_api]
use = egg:Paste#urlmap
/: sahara_apiv2
There are 2 significant changes occurring here; changing the authentication validator in the pipline, and changing the root "/" application to the new v2 handler.
At this point the sahara API server should be configured to accept requests on the new v2 endpoints.
Communicating with the v2 API
The v2 API makes at least one major change from the previous
versions, removing the OpenStack project identifier from the URL.
Instead of adding this UUID to the URL, it is now required to be
included as a header named OpenStack-Project-ID
.
For example, in previous versions of the API, a call to get the list of clusters for project "12345678-1234-1234-1234-123456789ABC" would have been made as follows:
GET /v1.1/12345678-1234-1234-1234-123456789ABC/clusters
X-Auth-Token: {valid auth token}
This call would now be made to the following URL, while including the
project identifier in a header named
OpenStack-Project-ID
:
GET /v2/clusters
X-Auth-Token: {valid auth token}
OpenStack-Project-ID: 12345678-1234-1234-1234-123456789ABC
Using a tool like HTTPie, the same request could be made like this:
$ httpie http://{sahara service ip:port}/v2/clusters \
X-Auth-Token:{valid auth token} \
OpenStack-Project-ID:12345678-1234-1234-1234-123456789ABC
Following the implementation progress
As the creation of this API will be under regular change until it moves out of the experimental phase, a wiki page has been established to help track the progress.
https://wiki.openstack.org/wiki/Sahara/api-v2
This page will help to coordinate the various reviews, specs, and work items that are a continuing facet of this work.
The API service layer
When contributing to the version 2 API, it will be necessary to add
code that modifies the data and behavior of HTTP calls as they are sent
to and from the processing engine and data abstraction layers. Most
frequently in the sahara codebase, these interactions are handled in the
modules of the sahara.service.api
package. This package
contains code for all versions of the API and follows a namespace
mapping that is similar to the routing functions of
sahara.api
Although these modules are not the definitive end of all answers to API related code questions, they are a solid starting point when examining the extent of new work. Furthermore, they serve as a central point to begin API debugging efforts when the need arises.