diff --git a/doc/source/api_curl_examples.rst b/doc/source/api_curl_examples.rst index c2ab00c643..9ad16156da 100644 --- a/doc/source/api_curl_examples.rst +++ b/doc/source/api_curl_examples.rst @@ -22,6 +22,72 @@ API Examples using Curl v3 API Examples Using Curl -------------------------- +GET / +===== + +Discover API version information, links to documentation (PDF, HTML, WADL), +and supported media types: + +.. WARNING:: + + The v2.0 portion of this response will be removed in the T release. It is + only advertised here because the v2.0 API supports the ec2tokens API until + the T release. All other functionality of the v2.0 has been removed as of + the Queens release. Use v3 for all functionality as it is more complete and + secure. + +.. code-block:: bash + + $ curl "http://localhost:5000" + +.. code-block:: javascript + + { + "versions": { + "values": [ + { + "id": "v3.10", + "links": [ + { + "href": "http://127.0.0.1:5000/v3/", + "rel": "self" + } + ], + "media-types": [ + { + "base": "application/json", + "type": "application/vnd.openstack.identity-v3+json" + } + ], + "status": "stable", + "updated": "2018-02-28T00:00:00Z" + }, + { + "id": "v2.0", + "links": [ + { + "href": "http://127.0.0.1:5000/v2.0/", + "rel": "self" + }, + { + "href": "https://docs.openstack.org/", + "rel": "describedby", + "type": "text/html" + } + ], + "media-types": [ + { + "base": "application/json", + "type": "application/vnd.openstack.identity-v2.0+json" + } + ], + "status": "deprecated", + "updated": "2016-08-04T00:00:00Z" + } + ] + } + } + Tokens ====== @@ -792,542 +858,3 @@ Example response: "trustor_user_id": "3ec3164f750146be97f21559ee4d9c51" } } - - -------------------------------- -Service API Examples Using Curl -------------------------------- - -The service API is defined to be a subset of the Admin API and, by -default, runs on port 5000. - -GET / -===== - -This call is identical to that documented for the Admin API, except -that it uses port 5000, instead of port 35357, by default: - -.. code-block:: bash - - $ curl "http://0.0.0.0:5000" - -or: - -.. code-block:: bash - - $ curl "http://0.0.0.0:5000/v2.0/" - -See the `Admin API Examples Using Curl`_ for more info. - -GET /extensions -=============== - -This call is identical to that documented for the Admin API. - -POST /tokens -============ - -This call is identical to that documented for the Admin API. - -GET /tenants -============ - -List all of the tenants your token can access: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:887665443383838" \ - "http://localhost:5000/v2.0/tenants" - -Returns: - -.. code-block:: javascript - - { - "tenants_links": [], - "tenants": [ - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } - ------------------------------ -Admin API Examples Using Curl ------------------------------ - -These examples assume a default port value of 35357, and depend on the -``sampledata`` bundled with keystone. - -GET / -===== - -Discover API version information, links to documentation (PDF, HTML, WADL), -and supported media types: - -.. code-block:: bash - - $ curl "http://0.0.0.0:35357" - -.. code-block:: javascript - - { - "versions": { - "values": [ - { - "id": "v3.4", - "links": [ - { - "href": "http://127.0.0.1:35357/v3/", - "rel": "self" - } - ], - "media-types": [ - { - "base": "application/json", - "type": "application/vnd.openstack.identity-v3+json" - } - ], - "status": "stable", - "updated": "2015-03-30T00:00:00Z" - }, - { - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:35357/v2.0/", - "rel": "self" - }, - { - "href": "https://docs.openstack.org/", - "rel": "describedby", - "type": "text/html" - } - ], - "media-types": [ - { - "base": "application/json", - "type": "application/vnd.openstack.identity-v2.0+json" - } - ], - "status": "stable", - "updated": "2014-04-17T00:00:00Z" - } - ] - } - } - -.. code-block:: bash - - $ curl "http://0.0.0.0:35357/v2.0/" - -Returns: - -.. code-block:: javascript - - { - "version": { - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:35357/v2.0/", - "rel": "self" - }, - { - "href": "https://docs.openstack.org/", - "rel": "describedby", - "type": "text/html" - } - ], - "media-types": [ - { - "base": "application/json", - "type": "application/vnd.openstack.identity-v2.0+json" - } - ], - "status": "stable", - "updated": "2014-04-17T00:00:00Z" - } - } - -GET /extensions -=============== - -Discover the API extensions enabled at the endpoint: - -.. code-block:: bash - - $ curl "http://localhost:35357/v2.0/extensions/" - -Returns: - -.. code-block:: javascript - - { - "extensions":{ - "values":[] - } - } - -POST /tokens -============ - -Authenticate by exchanging credentials for an access token: - -.. code-block:: bash - - $ curl -d ' - {"auth": { - "tenantName": "customer-x", - "passwordCredentials": { - "username": "joeuser", - "password": "secret" - } - } - }' \ - -H "Content-type: application/json" \ - "http://localhost:35357/v2.0/tokens" - -Returns: - -.. code-block:: javascript - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "serviceCatalog":[ - { - "endpoints":[ - { - "adminURL":"http://swift.admin-nets.local:8080/", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", - "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" - } - ], - "type":"object-store", - "name":"swift" - }, - { - "endpoints":[ - { - "adminURL":"http://cdn.admin-nets.local/v1.1/1", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:7777/v1.1/1", - "publicURL":"http://cdn.publicinternets.com/v1.1/1" - } - ], - "type":"object-store", - "name":"cdn" - } - ], - "user":{ - "id":"1", - "roles":[ - { - "tenantId":"1", - "id":"3", - "name":"Member" - } - ], - "name":"joeuser" - } - } - } - -.. note:: - - Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. - -GET /tokens/{token_id} -====================== - -.. note:: - - This call refers to a token known to be valid, ``887665443383838`` in this case. - -Validate a token: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" \ - "http://localhost:35357/v2.0/tokens/887665443383838" - -If the token is valid, returns: - -.. code-block:: javascript - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "user":{ - "name":"joeuser", - "tenantName":"customer-x", - "id":"1", - "roles":[ - { - "serviceId":"1", - "id":"3", - "name":"Member" - } - ], - "tenantId":"1" - } - } - } - -HEAD /tokens/{token_id} -======================= - -This is a high-performance variant of the GET call documented above, which -by definition, returns no response body: - -.. code-block:: bash - - $ curl -I -H "X-Auth-Token:999888777666" \ - "http://localhost:35357/v2.0/tokens/887665443383838" - -... which returns ``200``, indicating the token is valid:: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: None - Date: Tue, 08 Nov 2011 23:07:44 GMT - -GET /tokens/{token_id}/endpoints -================================ - -List all endpoints for a token: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" \ - "http://localhost:35357/v2.0/tokens/887665443383838/endpoints" - -Returns: - -.. code-block:: javascript - - { - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", - "rel": "next" - } - ], - "endpoints": [ - { - "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", - "name": "swift", - "adminURL": "http://swift.admin-nets.local:8080/", - "region": "RegionOne", - "tenantId": 1, - "type": "object-store", - "id": 1, - "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" - }, - { - "internalURL": "http://localhost:8774/v1.0", - "name": "nova_compat", - "adminURL": "http://127.0.0.1:8774/v1.0", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 2, - "publicURL": "http://nova.publicinternets.com/v1.0/" - }, - { - "internalURL": "http://localhost:8774/v1.1", - "name": "nova", - "adminURL": "http://127.0.0.1:8774/v1.1", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 3, - "publicURL": "http://nova.publicinternets.com/v1.1/ - }, - { - "internalURL": "http://127.0.0.1:9292/v1.1/", - "name": "glance", - "adminURL": "http://nova.admin-nets.local/v1.1/", - "region": "RegionOne", - "tenantId": 1, - "type": "image", - "id": 4, - "publicURL": "http://glance.publicinternets.com/v1.1/" - }, - { - "internalURL": "http://127.0.0.1:7777/v1.1/1", - "name": "cdn", - "adminURL": "http://cdn.admin-nets.local/v1.1/1", - "region": "RegionOne", - "tenantId": 1, - "type": "object-store", - "id": 5, - "publicURL": "http://cdn.publicinternets.com/v1.1/1" - } - ] - } - -GET /tenants -============ - -List all of the tenants in the system (requires an Admin ``X-Auth-Token``): - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" \ - "http://localhost:35357/v2.0/tenants" - -Returns: - -.. code-block:: javascript - - { - "tenants_links": [], - "tenants": [ - { - "enabled": false, - "description": "None", - "name": "project-y", - "id": "3" - }, - { - "enabled": true, - "description": "None", - "name": "ANOTHER:TENANT", - "id": "2" - }, - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } - -GET /tenants/{tenant_id} -======================== - -Retrieve information about a tenant, by tenant ID: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" \ - "http://localhost:35357/v2.0/tenants/1" - -Returns: - -.. code-block:: javascript - - { - "tenant":{ - "enabled":true, - "description":"None", - "name":"customer-x", - "id":"1" - } - } - -GET /tenants/{tenant_id}/users/{user_id}/roles -============================================== - -List the roles a user has been granted on a tenant: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" \ - "http://localhost:35357/v2.0/tenants/1/users/1/roles" - -Returns: - -.. code-block:: javascript - - { - "roles_links":[], - "roles":[ - { - "id":"3", - "name":"Member" - } - ] - } - -GET /users/{user_id} -==================== - -Retrieve information about a user, by user ID: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" \ - "http://localhost:35357/v2.0/users/1" - -Returns: - -.. code-block:: javascript - - { - "user":{ - "tenantId":"1", - "enabled":true, - "id":"1", - "name":"joeuser" - } - } - -GET /tokens/revoked -=================== - -Get the revocation list: - -.. code-block:: bash - - curl -s -H "X-Auth-Token: $OS_TOKEN" \ - "http://localhost:35357/v2.0/tokens/revoked" | - jq -r .signed | - openssl cms -verify \ - -certfile /etc/keystone/ssl/certs/signing_cert.pem \ - -CAfile /etc/keystone/ssl/certs/ca.pem \ - -inform PEM \ - -nosmimecap -nodetach -nocerts -noattr 2>/dev/null | - python -m json.tool - -Example response: - -.. code-block:: javascript - - { - "revoked": [ - { - "expires": "2014-06-10T21:40:14Z", - "id": "e6e2b5c9092751f88d2bcd30b09777a9" - }, - { - "expires": "2014-06-10T21:47:29Z", - "id": "883ef5d610bd1c68fbaa8ac528aa9f17" - }, - { - "expires": "2014-06-10T21:51:52Z", - "id": "41775ff4838f8f406b7bad28bea0dde6" - } - ] - }