4d7159e93f
* migration of resource server from openstackid to its own project * migration of marketplace api * added api tests * added CORS middleware * added SecurityHTTPHeadersWriterMiddleware Change-Id: Ib3d02feeb1e756de73d380238a043a7ac1ec7ecc
560 lines
16 KiB
ReStructuredText
560 lines
16 KiB
ReStructuredText
==================
|
|
OAuth 2.0 Rest API
|
|
==================
|
|
|
|
Schema
|
|
^^^^^^
|
|
|
|
All API access is over HTTPS, and accessed from the **https://openstackid-resources.org/**
|
|
domain. All data is sent and received as JSON.
|
|
|
|
Parameters
|
|
^^^^^^^^^^
|
|
|
|
Many API methods take optional parameters. For GET requests, any parameters not
|
|
specified as a segment in the path can be passed as an HTTP query string
|
|
|
|
Pagination
|
|
^^^^^^^^^^
|
|
|
|
Requests that return multiple items will be paginated to 10 items by default.
|
|
You can specify further pages with the **?page** parameter. For some
|
|
resources, you can also set a custom page size up to 100 with the **?per_page**
|
|
parameter.
|
|
|
|
Rate Limiting
|
|
^^^^^^^^^^^^^
|
|
|
|
This is configured per API endpoint.
|
|
You can check the returned HTTP headers of any API request to see your current
|
|
rate limit status::
|
|
|
|
X-RateLimit-Limit: 60
|
|
X-RateLimit-Remaining: 56
|
|
X-RateLimit-Reset: 1372700873
|
|
|
|
|
|
The headers tell you everything you need to know about your current rate limit
|
|
status :
|
|
|
|
======================= ==============================================================================
|
|
Header Name Description
|
|
======================= ==============================================================================
|
|
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour.
|
|
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
|
|
X-RateLimit-Reset The number of seconds remaining until the current rate limit window resets.
|
|
======================= ==============================================================================
|
|
|
|
If your application triggers this rate limit, you'll receive an informative
|
|
response:
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 403 Forbidden
|
|
Content-Type: application/json; charset=utf-8
|
|
Connection: close
|
|
|
|
{
|
|
|
|
"message": "You have triggered an abuse detection mechanism and have been
|
|
temporarily blocked. Please retry your request again later."
|
|
|
|
}
|
|
|
|
Conditional requests
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Most responses return an **ETag** header. You can use the values
|
|
of this headers to make subsequent requests to those resources using the
|
|
**If-None-Match** header, respectively. If the resource
|
|
has not changed, the server will return a **304 Not Modified**.
|
|
|
|
|
|
Cross Origin Resource Sharing
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from
|
|
any origin.
|
|
You can read the [CORS W3C Recommendation](http://www.w3.org/TR/cors), or
|
|
[this intro]
|
|
(http://code.google.com/p/html5security/wiki/CrossOriginRequestSecurity) from
|
|
the HTML 5 Security Guide.
|
|
|
|
JSON-P Callbacks
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
You can send a **?callback** parameter to any GET call to have the results
|
|
wrapped in a JSON function. This is typically used when browsers want to
|
|
embed OpenStack content in web pages by getting around cross domain issues.
|
|
The response includes the same data output as the regular API, plus the
|
|
relevant HTTP Header information.
|
|
|
|
|
|
MarketPlace API
|
|
^^^^^^^^^^^^^^^
|
|
|
|
Public Clouds Endpoints
|
|
-----------------------
|
|
|
|
Allows to get read only access to public clouds related data ( clouds and data
|
|
centers locations)
|
|
|
|
.. http:get:: /api/v1/marketplace/public-clouds
|
|
|
|
Get a list of public clouds
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/public-clouds HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: text/javascript
|
|
|
|
{
|
|
|
|
"total":20,
|
|
"per_page":10,
|
|
"current_page":1,
|
|
"last_page":2,
|
|
"from":1,
|
|
"to":10,
|
|
"data":[
|
|
{
|
|
"ID":"YYYY",
|
|
"Created":"2014-04-23 05:36:10",
|
|
"LastEdited":"2015-02-04 11:13:58",
|
|
"Name":"Next-Generation AgileCLOUD",
|
|
"Slug":"next-generation-agilecloud",
|
|
"Overview":"....",
|
|
"Call2ActionUri":"http:\/\/....",
|
|
"Active":"1",
|
|
"CompanyID":"XXX"
|
|
}
|
|
,{...}
|
|
]
|
|
|
|
}
|
|
|
|
:query page: used in conjunction with "per_page" query string parameter.
|
|
indicates the desired page number, when we want paginate
|
|
over results
|
|
:query per_page: used in conjunction with "page" query string parameter.
|
|
indicates the desired page size
|
|
:query status: (optional filter) allow us to get active, non active or all
|
|
public clouds
|
|
:query order_by: (optional) used in conjunction with query string parameter
|
|
"order_dir", point out the desired order of the result (date or name)
|
|
:query order_dir: (optional) used in conjunction with query string parameter
|
|
"order", point out the desired order direction of the result (asc or desc)
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 412: invalid parameters
|
|
:statuscode 500: server error
|
|
|
|
.. http:get:: api/v1/marketplace/public-clouds/(int:id)
|
|
|
|
Get desired public cloud point out by `id` param
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/public-clouds/123456 HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: text/javascript
|
|
|
|
{
|
|
"ID":"123456",
|
|
"Created":"2014-04-23 05:36:10",
|
|
"LastEdited":"2015-02-04 11:13:58",
|
|
"Name":"test public cloud",
|
|
"Slug":"test-public-cloud",
|
|
"Overview":"lorep ip sum",
|
|
"Call2ActionUri":"http:\/\/.../",
|
|
"Active":"1",
|
|
"CompanyID":"123456"
|
|
}
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 404: entity not found
|
|
:statuscode 500: server error
|
|
|
|
|
|
.. http:get:: /api/v1/marketplace/public-clouds/(int:id)/data-centers
|
|
|
|
Get data center locations for public cloud pointed out by `id` param
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/public-clouds/123456/data-centers HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: text/javascript
|
|
|
|
{"datacenters":[
|
|
{
|
|
"ID":"72",
|
|
"Created":"2014-05-07 15:19:39",
|
|
"LastEdited":"2014-05-07 15:19:39",
|
|
"Name":"West",
|
|
"Endpoint":"https:\/\/identity.uswest1.cloud.io.com\/v2.0",
|
|
"Color":"000000",
|
|
"locations":[
|
|
{
|
|
"ID":"109",
|
|
"Created":"2014-05-07 15:19:39",
|
|
"LastEdited":"2014-05-07 15:19:39",
|
|
"City":"Phoenix",
|
|
"State":"AZ",
|
|
"Country":"US",
|
|
"Lat":"33.45",
|
|
"Lng":"-112.07"
|
|
}
|
|
]
|
|
},...
|
|
]
|
|
}
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 404: entity not found (cloud)
|
|
:statuscode 500: server error
|
|
|
|
Private Clouds Endpoints
|
|
------------------------
|
|
|
|
Allows to get read only access to private clouds related data ( clouds and data
|
|
centers locations)
|
|
|
|
.. http:get:: /api/v1/marketplace/private-clouds
|
|
|
|
Get a list of private clouds
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/private-clouds HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: text/javascript
|
|
|
|
{
|
|
|
|
"total":20,
|
|
"per_page":10,
|
|
"current_page":1,
|
|
"last_page":2,
|
|
"from":1,
|
|
"to":10,
|
|
"data":[
|
|
{
|
|
"ID":"YYYY",
|
|
"Created":"2014-04-23 05:36:10",
|
|
"LastEdited":"2015-02-04 11:13:58",
|
|
"Name":"test private cloud",
|
|
"Slug":"test-private-cloud",
|
|
"Overview":"....",
|
|
"Call2ActionUri":"http:\/\/....",
|
|
"Active":"1",
|
|
"CompanyID":"XXX"
|
|
}
|
|
,{...}
|
|
]
|
|
|
|
}
|
|
|
|
:query page: used in conjunction with "per_page" query string parameter.
|
|
indicates the desired page number, when we want paginate
|
|
over results
|
|
:query per_page: used in conjunction with "page" query string parameter.
|
|
indicates the desired page size
|
|
:query status: (optional filter) allow us to get active, non active or all
|
|
public clouds
|
|
:query order_by: (optional) used in conjunction with query string parameter
|
|
"order_dir", point out the desired order of the result (date or name)
|
|
:query order_dir: (optional) used in conjunction with query string parameter
|
|
"order", point out the desired order direction of the result (asc or desc)
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 412: invalid parameters
|
|
:statuscode 500: server error
|
|
|
|
.. http:get:: /api/v1/marketplace/private-clouds/(int:id)
|
|
|
|
Get desired private cloud point out by `id` param
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/private-clouds/123456 HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: text/javascript
|
|
|
|
{
|
|
"ID":"123456",
|
|
"Created":"2014-04-23 05:36:10",
|
|
"LastEdited":"2015-02-04 11:13:58",
|
|
"Name":"test private cloud",
|
|
"Slug":"test-private-cloud",
|
|
"Overview":"lorep ip sum",
|
|
"Call2ActionUri":"http:\/\/..",
|
|
"Active":"1",
|
|
"CompanyID":"123456"
|
|
}
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 404: entity not found
|
|
:statuscode 500: server error
|
|
|
|
|
|
.. http:get:: /api/v1/marketplace/private-clouds/(int:id)/data-centers
|
|
|
|
Get data center locations for private cloud pointed out by `id` param
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/private-clouds/123456/data-centers HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: text/javascript
|
|
|
|
{"datacenters":[
|
|
{
|
|
"ID":"72",
|
|
"Created":"2014-05-07 15:19:39",
|
|
"LastEdited":"2014-05-07 15:19:39",
|
|
"Name":"West",
|
|
"Endpoint":"https:\/\/identity.uswest1.cloud.io.com\/v2.0",
|
|
"Color":"000000",
|
|
"locations":[
|
|
{
|
|
"ID":"109",
|
|
"Created":"2014-05-07 15:19:39",
|
|
"LastEdited":"2014-05-07 15:19:39",
|
|
"City":"Phoenix",
|
|
"State":"AZ",
|
|
"Country":"US",
|
|
"Lat":"33.45",
|
|
"Lng":"-112.07"
|
|
}
|
|
]
|
|
},...
|
|
]
|
|
}
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 404: entity not found (cloud)
|
|
:statuscode 500: server error
|
|
|
|
|
|
Consultants Endpoints
|
|
---------------------
|
|
|
|
Allows to get read only access to consultants related data ( consultants and
|
|
offices locations)
|
|
|
|
.. http:get:: /api/v1/marketplace/consultants
|
|
|
|
Get a list of consultants
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/consultants HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: text/javascript
|
|
|
|
{
|
|
|
|
"total":20,
|
|
"per_page":10,
|
|
"current_page":1,
|
|
"last_page":2,
|
|
"from":1,
|
|
"to":10,
|
|
"data":[
|
|
{
|
|
"ID":"YYYY",
|
|
"Created":"2014-04-23 05:36:10",
|
|
"LastEdited":"2015-02-04 11:13:58",
|
|
"Name":"Consultant Name",
|
|
"Slug":"consultant-name",
|
|
"Overview":"....",
|
|
"Call2ActionUri":"http:\/\/....",
|
|
"Active":"1",
|
|
"CompanyID":"XXX"
|
|
}
|
|
,{...}
|
|
]
|
|
|
|
}
|
|
|
|
:query page: used in conjunction with "per_page" query string parameter.
|
|
indicates the desired page number, when we want paginate
|
|
over results
|
|
:query per_page: used in conjunction with "page" query string parameter.
|
|
indicates the desired page size
|
|
:query status: (optional filter) allow us to get active, non active or all
|
|
public clouds
|
|
:query order_by: (optional) used in conjunction with query string parameter
|
|
"order_dir", point out the desired order of the result (date or name)
|
|
:query order_dir: (optional) used in conjunction with query string parameter
|
|
"order", point out the desired order direction of the result (asc or desc)
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 412: invalid parameters
|
|
:statuscode 500: server error
|
|
|
|
.. http:get:: /api/v1/marketplace/consultants/(int:id)
|
|
|
|
Get desired consultant point out by `id` param
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/consultants/123456 HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: text/javascript
|
|
|
|
{
|
|
"ID":"123456",
|
|
"Created":"2014-04-23 05:36:10",
|
|
"LastEdited":"2015-02-04 11:13:58",
|
|
"Name":"Consultant Name",
|
|
"Slug":"consultant_name",
|
|
"Overview":"lorep ip sum",
|
|
"Call2ActionUri":"http:\/\/...",
|
|
"Active":"1",
|
|
"CompanyID":"123456"
|
|
}
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 404: entity not found
|
|
:statuscode 500: server error
|
|
|
|
.. http:get:: /api/v1/marketplace/consultants/(int:id)/offices
|
|
|
|
Get offices locations for consultant pointed out by `id` param
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1/marketplace/consultants/123456/offices HTTP/1.1
|
|
Host: openstackid.org
|
|
Accept: application/json, text/javascript
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: text/javascript
|
|
|
|
{
|
|
"offices":[
|
|
{
|
|
"ID":"45",
|
|
"Created":"2014-04-29 16:02:50",
|
|
"LastEdited":"2014-04-29 16:02:50",
|
|
"Address":null,
|
|
"Address2":null,
|
|
"State":"CA",
|
|
"ZipCode":null,
|
|
"City":"Mountain View",
|
|
"Country":"US",
|
|
"Lat":"37.39",
|
|
"Lng":"-122.08"
|
|
},...
|
|
]
|
|
}
|
|
|
|
:reqheader Authorization: OAuth 2.0 Bearer Access Token
|
|
|
|
:statuscode 200: no error
|
|
:statuscode 404: entity not found (consultant)
|
|
:statuscode 500: server error |