f41bb7dd26
Pagination abilities are described in doc/source/restapi.rst file and in api-ref Change-Id: Ia653f1fb22a640299a1d2642ea11d9b0215dc000 bp: pagination
124 lines
4.0 KiB
ReStructuredText
124 lines
4.0 KiB
ReStructuredText
Sahara REST API v1.1
|
|
*********************
|
|
|
|
1 General API information
|
|
=========================
|
|
|
|
This section contains base info about the sahara REST API design.
|
|
|
|
1.1 Authentication and Authorization
|
|
------------------------------------
|
|
|
|
The sahara API uses the OpenStack Identity service as the default
|
|
authentication service. When the Identity service is enabled, users who
|
|
submit requests to the sahara service must provide an authentication token in
|
|
the ``X-Auth-Token`` request header. A user can obtain the token by
|
|
authenticating to the Identity service endpoint. For more information about
|
|
the Identity service, please see the `keystone project developer documentation
|
|
<http://docs.openstack.org/developer/keystone/>`_
|
|
|
|
With each request, a user must specify the OpenStack tenant(now known as
|
|
project) in the url path, for example: '/v1.1/{tenant_id}/clusters'. Sahara
|
|
will perform the requested operation in the specified tenant using the
|
|
provided credentials. Therefore, clusters may be created and managed only
|
|
within tenants to which the user has access.
|
|
|
|
1.2 Request / Response Types
|
|
----------------------------
|
|
|
|
The sahara API supports the JSON data serialization format. This means that
|
|
for requests that contain a body, the ``Content-Type`` header must be set to
|
|
the MIME type value ``application/json``. Also, clients should accept JSON
|
|
serialized responses by specifying the ``Accept`` header with the MIME type
|
|
value ``application/json`` or adding the ``.json`` extension to the resource
|
|
name. The default response format is ``application/json`` if the client does
|
|
not specify an ``Accept`` header or append the ``.json`` extension in the URL
|
|
path.
|
|
|
|
Example:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /v1.1/{tenant_id}/clusters.json
|
|
|
|
or
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /v1.1/{tenant_id}/clusters
|
|
Accept: application/json
|
|
|
|
1.3 Navigation by response
|
|
--------------------------
|
|
Sahara API supports delivering response data by pages. User can pass
|
|
two parameters in API GET requests which return an array of objects.
|
|
The parameters are:
|
|
|
|
``limit`` - maximum number of objects in response data.
|
|
This parameter must be a positive integer number.
|
|
|
|
``marker`` - ID of the last element on the list which won't be in response.
|
|
|
|
Example:
|
|
Get 15 clusters after cluster with id=d62ad147-5c10-418c-a21a-3a6597044f29:
|
|
|
|
.. soursecode:: http
|
|
|
|
GET /v1.1/{tenant_id}/clusters?limit=15&marker=d62ad147-5c10-418c-a21a-3a6597044f29
|
|
|
|
For convenience, response contains markers of previous and following pages
|
|
which are named 'prev' and 'next' fields. Also there is ``sort_by`` parameter
|
|
for sorting objects. Sahara API supports ascending and descending sorting.
|
|
|
|
Examples:
|
|
Sort clusters by name:
|
|
|
|
.. soursecode:: http
|
|
|
|
GET /v1.1/{tenant_id}/clusters?sort_by=name
|
|
|
|
Sort clusters by date of creation in descending order:
|
|
|
|
.. soursecode:: http
|
|
|
|
GET /v1.1/{tenant_id}/clusters?sort_by=-created_at
|
|
|
|
|
|
1.4 Faults
|
|
----------
|
|
The sahara API returns an error response if a failure occurs while
|
|
processing a request. Sahara uses only standard HTTP error codes. 4xx errors
|
|
indicate problems in the particular request being sent from the client and
|
|
5xx errors indicate server-side problems.
|
|
|
|
The response body will contain richer information about the cause of the
|
|
error. An error response follows the format illustrated by the following
|
|
example:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 400 BAD REQUEST
|
|
Content-type: application/json
|
|
Content-length: 126
|
|
|
|
{
|
|
"error_name": "CLUSTER_NAME_ALREADY_EXISTS",
|
|
"error_message": "Cluster with name 'test-cluster' already exists",
|
|
"error_code": 400
|
|
}
|
|
|
|
|
|
The ``error_code`` attribute is an HTTP response code. The ``error_name``
|
|
attribute indicates the generic error type without any concrete ids or
|
|
names, etc. The last attribute, ``error_message``, contains a human readable
|
|
error description.
|
|
|
|
2 API
|
|
=====
|
|
|
|
- `Sahara REST API Reference (OpenStack API Complete Reference -
|
|
DataProcessing)`_
|
|
.. _`Sahara REST API Reference (OpenStack API Complete Reference - DataProcessing)`: http://api.openstack.org/api-ref-data-processing-v1.1.html
|
|
|
|
|