================== 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