openstack/sahara
Code Issues Proposed changes

Updating the rest api documentation

Browse Source 
* formatting text for 79 chars
* many small grammar changes

Change-Id: I853fa8cf2690b556eb966278473c4936051bb592
Partial-Bug: 1490687
This commit is contained in:
Michael McCune 2015-08-31 14:47:41 -04:00
parent 6b7e3a0271
commit 41afce412a
1 changed files with 31 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
doc/source/restapi.rst
View File

@ -4,29 +4,35 @@ Sahara REST API v1.1
1 General API information 1 General API information
========================= =========================
This section contains base info about the Sahara REST API design. This section contains base info about the sahara REST API design.
1.1 Authentication and Authorization 1.1 Authentication and Authorization
------------------------------------ ------------------------------------
The Sahara API uses the Keystone Identity Service as the default authentication service. The sahara API uses the OpenStack Identity service as the default
When Keystone is enabled, users who submit requests to the Sahara service must provide an authentication token authentication service. When the Identity service is enabled, users who
in the X-Auth-Token request header. A user can obtain the token by authenticating to the Keystone endpoint. submit requests to the sahara service must provide an authentication token in
For more information about Keystone, see the OpenStack Identity Developer Guide. 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/>`_
Also with each request a user must specify the OpenStack tenant in the url path, for example: '/v1.1/{tenant_id}/clusters'. With each request, a user must specify the OpenStack tenant(now known as
Sahara will perform the requested operation in the specified tenant using the provided credentials. project) in the url path, for example: '/v1.1/{tenant_id}/clusters'. Sahara
Therefore, clusters may be created and managed only within tenants to which the user has access. 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 1.2 Request / Response Types
---------------------------- ----------------------------
The Sahara API supports the JSON data serialization format. The sahara API supports the JSON data serialization format. This means that
This means that for requests that contain a body, the Content-Type header must be set to the MIME type value for requests that contain a body, the ``Content-Type`` header must be set to
"application/json". Also, clients should accept JSON serialized responses by specifying the Accept header the MIME type value ``application/json``. Also, clients should accept JSON
with the MIME type value "application/json" or adding the ".json" extension to the resource name. serialized responses by specifying the Accept header with the MIME type
The default response format is "application/json" if the client does not specify an Accept header value ``application/json`` or adding the ``.json`` extension to the resource
or append the ".json" extension in the URL path. 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: Example:
@ -44,12 +50,14 @@ or
1.3 Faults 1.3 Faults
---------- ----------
The Sahara API returns an error response if a failure occurs while processing a request. The sahara API returns an error response if a failure occurs while
Sahara uses only standard HTTP error codes. 4xx errors indicate problems in the particular processing a request. Sahara uses only standard HTTP error codes. 4xx errors
request being sent from the client and 5xx errors indicate server-side problems. 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. The response body will contain richer information about the cause of the
An error response follows the format illustrated by the following example: error. An error response follows the format illustrated by the following
example:
.. sourcecode:: http .. sourcecode:: http
@ -64,9 +72,10 @@ An error response follows the format illustrated by the following example:
} }
The 'error_code' attribute is an HTTP response code. The 'error_name' attribute The ``error_code`` attribute is an HTTP response code. The ``error_name``
indicates the generic error type without any concrete ids or names, etc. attribute indicates the generic error type without any concrete ids or
The last attribute, 'error_message', contains a human readable error description. names, etc. The last attribute, ``error_message``, contains a human readable
error description.
2 API 2 API
===== =====