From a47eba6e4c30407cf9f491f477b20c05e2392b04 Mon Sep 17 00:00:00 2001 From: Diane Fleming Date: Wed, 30 Jul 2014 15:33:54 -0500 Subject: [PATCH] Remove ATOM responses for list versions and get version details. Once https://review.openstack.org/#/c/110768/ merges, the JSON and XML list versions responses will update. Also, other clean-up (formatting, future tense) Change-Id: If9248bdd9e73ccc7ac7871aa8981925eb5a889d4 Closes-Bug: #1338120 --- v2.0/src/ch_identity-client-api.xml | 17 +- v2.0/src/ch_identity-general-api-info.xml | 492 +++++++++------------- v2.0/src/ch_identity-service-api.xml | 66 +-- v2.0/src/identity-dev-guide.xml | 39 +- v2.0/src/samples/choices.xml | 42 +- v2.0/src/samples/ext-getuser.xml | 10 +- v2.0/src/samples/getuser-1.xml | 14 +- v2.0/src/samples/identity_fault.xml | 9 +- v2.0/src/section_identity-concepts.xml | 4 +- 9 files changed, 301 insertions(+), 392 deletions(-) diff --git a/v2.0/src/ch_identity-client-api.xml b/v2.0/src/ch_identity-client-api.xml index b7e194c6..bf5c99f0 100644 --- a/v2.0/src/ch_identity-client-api.xml +++ b/v2.0/src/ch_identity-client-api.xml @@ -1,12 +1,11 @@ - + Client operations - These operations enable clients to get API version and - extension information, and get authentication tokens. + These operations enable clients to get API version and extension information, and get + authentication tokens.
API versions @@ -40,10 +39,6 @@ href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/wadl/identity.wadl#tokens"> -
diff --git a/v2.0/src/ch_identity-general-api-info.xml b/v2.0/src/ch_identity-general-api-info.xml index d1bcf22a..ed8f5656 100644 --- a/v2.0/src/ch_identity-general-api-info.xml +++ b/v2.0/src/ch_identity-general-api-info.xml @@ -38,82 +38,80 @@ This operation does not require a request body.'> '> ]> - + General API information - The OpenStack Identity API is implemented using a RESTful - web service interface. All requests to authenticate and - operate against the OpenStack Identity API should be performed + The OpenStack Identity API is implemented using a RESTful web service interface. All + requests to authenticate and operate against the OpenStack Identity API should be performed using SSL over HTTP (HTTPS) on TCP port 443. -
- Request and response types - The OpenStack Identity API supports both the JSON and - XML data serialization formats. The request format is - specified using the Content-Type header and - is required for operations that have a request body. The - response format can be specified in requests using either - the Accept header or adding an - .xml or .json extension to - the request URI. Note that it is possible for a response - to be serialized using a format different from the request - (see example below). If no response format is specified, - JSON is the default. If conflicting formats are specified - using both an Accept header and a query - extension, the query extension takes precedence. - - - - - - - - - - - - - - - - - - - - - - - - -
Response types
FormatAccept HeaderQuery ExtensionDefault
JSONapplication/json.jsonYes
XMLapplication/xml.xmlNo
- - JSON request with headers +
+ Request and response formats + The OpenStack Identity API supports both JSON and XML data serialization request and + response formats. + Use the Content-Type request header to specify the request format. This + header is required for operations that have a request body. + The syntax for the Content-Type header is: + Content-Type: application/FORMAT + Where FORMAT is either json or + xml. + Use one of the following methods to specify the response format: + + + Accept header + + The syntax for the Accept header is: + Accept: application/FORMAT + Where FORMAT is either json + or xml. The default format is + json. + + + + Query extension + + Add an .xml or .json extension to + the request URI. For example, the .xml extension in the + following list servers URI request specifies that the response body is to be + returned in XML format: + &GET; publicURL/servers.xml + + + + If you do not specify a response format, JSON is the default. + If the Accept header and the query extension specify conflicting formats, + the format specified in the query extension takes precedence. For example, if the query + extension is .xml and the Accept header specifies + application/json, the response is returned in XML format. + You can serialize a response in a different format from the request format. + shows a request body in JSON format and shows a response body in XML format. + + Request with headers: JSON - - XML response with headers + shows the headers and XML response returned by the JSON + request: + + Response with headers: XML
Content compression - Request and response body data may be encoded with gzip - compression in order to accelerate interactive performance - of API calls and responses. This is controlled using the - Accept-Encoding header on the request - from the client and indicated by the - Content-Encoding header in the server - response. Unless the header is explicitly set, encoding - defaults to disabled. + Request and response body data may be encoded with gzip compression in order to + accelerate interactive performance of API calls and responses. This is controlled using + the Accept-Encoding header on the request from the client and indicated by + the Content-Encoding header in the server response. Unless the header is + explicitly set, encoding defaults to disabled. - + @@ -134,60 +132,47 @@ This operation does not require a request body.'>
Paginated collections - To reduce load on the service, list operations return a - maximum number of items at a time. The maximum number of - items returned is determined by the Identity provider. To - navigate the collection, you can set the - limit and - marker parameters in the URI. - For example, - ?limit=100&marker=1234. - The marker parameter is the ID of - the last item in the previous list. Items are sorted by - update time. When an update time is not available they are - sorted by ID. The limit parameter - sets the page size. Both parameters are optional. If the - client requests a limit beyond that - which is supported by the deployment an overLimit - (413) fault might be thrown. A - marker with an invalid ID will return an itemNotFound - (404) fault. + To reduce load on the service, list operations return a maximum number of items at a + time. The maximum number of items returned is determined by the Identity provider. To + navigate the collection, you can set the limit and + marker parameters in the URI. For example, + ?limit=100&marker=1234. The + marker parameter is the ID of the last item in the previous + list. Items are sorted by update time. When an update time is not available they are + sorted by ID. The limit parameter sets the page size. Both + parameters are optional. If the client requests a limit beyond + that which is supported by the deployment an overLimit + (413) fault might be thrown. A marker with an invalid ID + returns an itemNotFound (404) + fault. - Paginated collections never return itemNotFound - (404) faults when the - collection is empty — clients should expect an - empty collection. + Paginated collections never return itemNotFound (404) + faults when the collection is empty — clients should expect an empty + collection. - For convenience, collections contain atom "next" and - "previous" links. The first page in the list will not - contain a "previous" link, the last page in the list will - not contain a "next" link. The following examples - illustrate three pages in a collection of tenants. The - first page was retrieved through a &GET; to - http://identity.api.openstack.org/v2.0/1234/tenants?limit=1. - In these examples, the limit - parameter sets the page size to a single item. Subsequent - "next" and "previous" links will honor the initial page - size. Thus, a client might follow links to traverse a - paginated collection without having to input the - marker parameter. + For convenience, collections contain atom "next" and "previous" links. The first page + in the list does not contain a previous link, the last page in the + list does not contain a next link. The following examples illustrate + three pages in a collection of tenants. The first page was retrieved through a &GET; to + http://identity.api.openstack.org/v2.0/1234/tenants?limit=1. In + these examples, the limit parameter sets the page size to a + single item. Subsequent next and previous links + honor the initial page size. Thus, a client might follow links to traverse a paginated + collection without having to input the marker parameter. Tenant collection, first page: XML response - Tenant collection, first page: JSON - response + Tenant collection, first page: JSON response - Tenant collection, second page: XML - response + Tenant collection, second page: XML response - Tenant collection, second page: JSON - response + Tenant collection, second page: JSON response @@ -198,16 +183,13 @@ This operation does not require a request body.'> Tenant collection, last page: JSON response - In the JSON representation, paginated collections - contain a values property that - contains the items in the collections. Links are accessed - via the links property. The approach - allows for extensibility of both the collection members - and of the paginated collection itself. It also allows - collections to be embedded in other objects as illustrated - below. Here, a subset of groups are presented within a - user. Clients must follow the "next" link to continue to - retrieve additional groups belonging to a user. + In the JSON representation, paginated collections contain a + values property that contains the items in the collections. + Links are accessed via the links property. The approach allows for + extensibility of both the collection members and of the paginated collection itself. It + also allows collections to be embedded in other objects as illustrated below. Here, a + subset of groups are presented within a user. Clients must follow the "next" link to + continue to retrieve additional groups belonging to a user. Paginated roles in user: XML response @@ -219,19 +201,15 @@ This operation does not require a request body.'>
Versions - The OpenStack Identity API uses both a URI and a MIME - type versioning scheme. In the URI scheme, the first - element of the path contains the target version identifier - (for example, https://identity.api.openstack.org/ - v2.0/…). The MIME type versioning scheme uses HTTP - content negotiation where the Accept or - Content-Type headers contains a MIME type - that includes the version ID as a parameter - (application/vnd.openstack.identity+xml;version=1.1). A - version MIME type is always linked to a base MIME type - (application/xml or application/json). If conflicting - versions are specified using both an HTTP header and a - URI, the URI takes precedence. + The OpenStack Identity API uses both a URI and a MIME type versioning scheme. In the + URI scheme, the first element of the path contains the target version identifier (for + example, https://identity.api.openstack.org/ v2.0/…). The MIME type versioning + scheme uses HTTP content negotiation where the Accept or + Content-Type headers contains a MIME type that includes the version ID + as a parameter (application/vnd.openstack.identity+xml;version=1.1). A version MIME type + is always linked to a base MIME type (application/xml or application/json). If + conflicting versions are specified using both an HTTP header and a URI, the URI takes + precedence. Request with MIME type versioning GET /tenants HTTP/1.1 @@ -244,86 +222,62 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb GET /v1.1/tenants HTTP/1.1 Host: identity.api.openstack.org Accept: application/xml -X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - The MIME type versioning approach allows for the - creation of permanent links, because the version - scheme is not specified in the URI path: - https://api.identity.openstack.org/tenants/12234. - + The MIME type versioning approach allows for the creation of permanent links, + because the version scheme is not specified in the URI path: + https://api.identity.openstack.org/tenants/12234. - If a request is made without a version specified in the - URI or via HTTP headers, then a multiple-choices response - (300) will follow providing - links and MIME types to available versions. + If a request is made without a version specified in the URI or through HTTP headers, a + multiple-choices response (300) provides links and MIME types + to available versions. - Multiple choices response: XML + Multiple choices: XML response - Multiple choices response: JSON + Multiple choices: JSON response - New features and functionality that do not break - API-compatibility will be introduced in the current - version of the API as extensions (see below) and the URI - and MIME types will remain unchanged. Features or - functionality changes that would necessitate a break in - API-compatibility will require a new version, which will - result in URI and MIME type version being updated - accordingly. When new API versions are released, older - versions will be marked as DEPRECATED. - Providers should work with developers and partners to - ensure there is adequate time to migrate to the new - version before deprecated versions are - discontinued. - Your application can programmatically determine - available API versions by performing a &GET; on the root - URL (such as, with the version and everything to the right - of it truncated) returned from the authentication system. - Note that an Atom representation of the versions resources - is supported when issuing a request with the - Accept header containing - application/atom+xml or by adding a .atom to the request - URI. This allows standard Atom clients to track version - changes. + New features and functionality that do not break API-compatibility are introduced in + the current version of the API as extensions (see the following section) and the URI and + MIME types remain unchanged. Features or functionality changes that would necessitate a + break in API-compatibility require a new version, which results in URI and MIME type + versions being updated accordingly. When new API versions are released, older versions + are marked as DEPRECATED. Providers should work with developers and + partners to ensure adequate migration time to the new version before deprecated versions + are discontinued. + Your application can programmatically determine available API versions by performing a + &GET; on the root URL (such as, with the version and everything to the right of it + truncated) returned from the authentication system. Note that an Atom representation of + the versions resources is supported when issuing a request with the Accept + header containing application/atom+xml or by adding a .atom to the request URI. This + enables standard Atom clients to track version changes. List versions: HTTP request GET HTTP/1.1 Host: identity.api.openstack.org - &CODES;200, - 203 - &ERROR_CODES; badRequest - (400), identityFault + &CODES;200, 203 + &ERROR_CODES; badRequest (400), identityFault (500), - serviceUnavailable(503) - &NO_REQUEST; + serviceUnavailable(503) &NO_REQUEST; List versions: XML response - - List versions: Atom response - - List versions: JSON response - You can also obtain additional information about a - specific version by performing a &GET; on the base version - URL (for example, - https://identity.api.openstack.org/v1.1/). Version request - URLs should always end with a trailing slash (/). If the - slash is omitted, the server might respond with a - 302 redirection request. - Format extensions might be placed after the slash (for - example, https://identity.api.openstack.org/v1.1/.xml). - Note that this is a special case that does not hold true - for other API requests. In general, requests such as - /tenants.xml and /tenants/.xml are handled - equivalently. + You can also obtain additional information about a specific version by performing a + &GET; on the base version URL (for example, https://identity.api.openstack.org/v1.1/). + Version request URLs should always end with a trailing slash (/). If the slash is + omitted, the server might respond with a 302 redirection + request. Format extensions might be placed after the slash (for example, + https://identity.api.openstack.org/v1.1/.xml). Note that this is a special case that + does not hold true for other API requests. In general, requests such as /tenants.xml and + /tenants/.xml are handled equivalently. Get version details: HTTP request @@ -331,47 +285,34 @@ GET HTTP/1.1 Host: identity.api.openstack.org/v1.1/ - &CODES;200, - 203 - &ERROR_CODES; badRequest - (400), identityFault + &CODES;200, 203 + &ERROR_CODES; badRequest (400), identityFault (500), - serviceUnavailable(503) - &NO_REQUEST; + serviceUnavailable(503) &NO_REQUEST; Get version details: XML response - - Get version details: Atom response - - Get version details: JSON response - The detailed version response contains pointers to both - a human-readable and a machine-processable description of - the API service. The machine-processable description is - written in the Web Application Description Language - (WADL). + The detailed version response contains pointers to both a human-readable and a + machine-processable description of the API service. The machine-processable description + is written in the Web Application Description Language (WADL). - If there is a discrepancy between the two - specifications, the WADL is authoritative as it - contains the most accurate and up-to-date description - of the API service. + If there is a discrepancy between the two specifications, the WADL is + authoritative as it contains the most accurate and up-to-date description of the API + service.
Extensions - The OpenStack Identity API is extensible. Extensions - serve two purposes: They allow the introduction of new - features in the API without requiring a version change and - they allow the introduction of vendor specific niche - functionality. Applications can programmatically determine - what extensions are available by performing a &GET; on the - /extensions URI. Note that this is a versioned request - — that is, an extension available in one API version - might not be available in another. + The OpenStack Identity API is extensible. Extensions serve two purposes: They allow + the introduction of new features in the API without requiring a version change and they + allow the introduction of vendor specific niche functionality. Applications can + programmatically determine what extensions are available by performing a &GET; on the + /extensions URI. Note that this is a versioned request — that is, an extension + available in one API version might not be available in another.
@@ -384,34 +325,29 @@ Host: identity.api.openstack.org/v1.1/ - + - &CODES;200, - 203 - &ERROR_CODES; badRequest - (400), identityFault + &CODES;200, 203 + &ERROR_CODES; badRequest (400), identityFault (500), - serviceUnavailable(503) - &NO_REQUEST; Each extension is identified by two unique - identifiers, a namespace and an - alias. Additionally an extension - contains documentation links in various formats. + serviceUnavailable(503) &NO_REQUEST; Each + extension is identified by two unique identifiers, a namespace and + an alias. Additionally an extension contains documentation links in + various formats. - List extensions: XML + List extensions: XML response - List extensions: JSON + List extensions: JSON response - Extensions might also be queried individually by their - unique alias. This provides the simplest method of - checking if an extension is available as an unavailable - extension will issue an itemNotFound - (404) response. + Extensions might also be queried individually by their unique alias. This provides the + simplest method of checking if an extension is available as an unavailable extension + issues an itemNotFound (404) + response. @@ -423,90 +359,72 @@ Host: identity.api.openstack.org/v1.1/ - - + + - &CODES;200, - 203 - &ERROR_CODES; itemNotFound - (404), badRequest - (400), identityFault - (500), - serviceUnavailable(503) - &NO_REQUEST; - List extensions: XML response + &CODES;200, 203 + &ERROR_CODES; itemNotFound (404), badRequest + (400), identityFault (500), + serviceUnavailable(503) &NO_REQUEST; + Show extension details: XML response - List extensions: JSON response + Show extension details: JSON response - Extensions can define new data types, parameters, - actions, headers, states, and resources. In XML, - additional elements and attributes might be defined. These - elements must be defined in the extension's namespace. In - JSON, the alias must be used. The volumes element in the - and - is defined in the RS-META namespace. Extended - headers are always prefixed with X- followed - by the alias and a dash: (X-RS-META-HEADER1). - Parameters must be prefixed with the extension alias - followed by a colon. + Extensions can define new data types, parameters, actions, headers, states, and + resources. In XML, additional elements and attributes might be defined. These elements + must be defined in the extension's namespace. In JSON, the alias must be used. The + volumes element in the and + is defined in the + RS-META namespace. Extended headers are always prefixed with + X- followed by the alias and a dash: (X-RS-META-HEADER1). + Parameters must be prefixed with the extension alias followed by a colon. - Applications should be prepared to ignore response - data that contains extension elements. Also, - applications should also verify that an extension is - available before submitting an extended - request. + Applications should ignore response data that contains extension elements. Also, + applications should also verify that an extension is available before submitting an + extended request. - Extended User Response: XML + Show user details: XML response - Extended User Response: JSON + Show user details: JSON response
Faults - When an error occurs, the system returns an HTTP error - response code denoting the type of error. The system also - returns additional information about the fault in the body - of the response. + When an error occurs, the system returns an HTTP error response code denoting the type + of error. The system also returns additional information about the fault in the body of + the response. - XML Fault Response + Identity fault: XML response - JSON Fault Response + Identity fault: JSON response - The error code is returned in the body of the response - for convenience. The message section returns a human - readable message. The details section is optional and - might contain useful information for tracking down an - error (such as, a stack trace). - The root element of the fault (for example, - identityFault) might change depending on the type of - error. The following is an example of an itemNotFound - error. + The response body returns the error code for convenience. The message section returns + a human readable message. The details section is optional and might contain useful + information for tracking down an error (such as, a stack trace). + The root element of the fault (for example, identityFault) + might change depending on the type of error. The following is an example of an + itemNotFound error. - XML Not Found Fault + itemNotFound fault: XML response - JSON Not Found Fault + itemNotFound fault: JSON response - The following list shows the possible fault types with - associated error codes. + The following table shows the possible fault types with associated error codes:
Compression headers
Header TypeHeader type Name Value
&GET; /extensionsReturns a list of available - extensionsReturns a list of available extensions
&GET;/extensions/aliasReturn details of a single - extension/extensions/aliasReturn details of a single extension
@@ -564,12 +482,10 @@ Host: identity.api.openstack.org/v1.1/
Fault types
- From an XML schema perspective, all API faults are - extensions of the base fault type - identityFault. When working with a system - that binds XML to actual classes (such as JAXB), one - should be capable of using identityFault as a - “catch-all” if there's no interest in distinguishing - between individual fault types. + From an XML schema perspective, all API faults are extensions of the base + identityFault fault type. When working with a system that + binds XML to actual classes (such as JAXB), one should be capable of using + identityFault as a “catch-all” if there's no interest in + distinguishing between individual fault types.
diff --git a/v2.0/src/ch_identity-service-api.xml b/v2.0/src/ch_identity-service-api.xml index f9dc510f..5b97bf05 100644 --- a/v2.0/src/ch_identity-service-api.xml +++ b/v2.0/src/ch_identity-service-api.xml @@ -8,28 +8,23 @@ xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns:html="http://www.w3.org/1999/xhtml" xml:id="Service_API_Admin_Operations" version="5.0" role="api-reference"> Administrative operations - The OpenStack Identity API administrative operations enable - service developers to get and validate access tokens, manage - users, tenants, roles, and service endpoints. - Most administrative API calls require authentication. The - only calls available without authentication are the calls to - discover the service – getting version info, WADL - contract, dev guide, help, and so on – and the call to - authenticate and get a token. - Authentication is performed by passing in a valid token in - the X-Auth-Token header on the request from the - client. The Identity API verifies that the token has, or - belongs to a user that has, the Admin - role. - For information about how to create your first - administrator, see the OpenStack Cloud Administrator - Guide. + The OpenStack Identity API administrative operations enable service developers to get and + validate access tokens, manage users, tenants, roles, and service endpoints. + Most administrative API calls require authentication. The only calls available without + authentication are the calls to discover the service – getting version info, WADL + contract, dev guide, help, and so on – and the call to authenticate and get a + token. + Authentication is performed by passing in a valid token in the X-Auth-Token + header on the request from the client. The Identity API verifies that the token has, or + belongs to a user that has, the Admin role. + For information about how to create your first administrator, see the OpenStack + Cloud Administrator Guide.
Versions - + @@ -37,10 +32,12 @@
Extensions - + - + @@ -48,10 +45,12 @@
Tokens - + - + @@ -60,20 +59,25 @@
Users - + - + - + - + - + @@ -81,11 +85,13 @@
Tenants - + - + - + OpenStack Identity API v2.0 Reference - Identity API Reference @@ -31,18 +27,26 @@ - Copyright details are filled in by the - template. + Copyright details are filled in by the template. - This document describes how to develop applications - that use the OpenStack Identity API v2.0 for - authentication. This document also describes how to - integrate services with the OpenStack Identity API - v2.0. + This document describes how to develop applications that use the OpenStack + Identity API v2.0 for authentication. This document also describes how to integrate + services with the OpenStack Identity API v2.0. + + 2014-07-29 + + + + Removed ATOM responses for list versions and get version details + calls. + + + + 2014-07-20 @@ -58,8 +62,8 @@ - Added missing code samples and - request parameter descriptions. + Added missing code samples and request parameter + descriptions. @@ -69,8 +73,7 @@ - Added back missing client operations - and extensions. + Added back missing client operations and extensions. diff --git a/v2.0/src/samples/choices.xml b/v2.0/src/samples/choices.xml index 31029642..cc4a77e5 100644 --- a/v2.0/src/samples/choices.xml +++ b/v2.0/src/samples/choices.xml @@ -1,38 +1,30 @@ - + - - + + - + - - + + - + - - + + - + - + \ No newline at end of file diff --git a/v2.0/src/samples/ext-getuser.xml b/v2.0/src/samples/ext-getuser.xml index fb0e7216..7a38d315 100644 --- a/v2.0/src/samples/ext-getuser.xml +++ b/v2.0/src/samples/ext-getuser.xml @@ -1,10 +1,8 @@ - - + + MetaValue1 MetaValue2 - + \ No newline at end of file diff --git a/v2.0/src/samples/getuser-1.xml b/v2.0/src/samples/getuser-1.xml index 0f9e6849..f932b904 100644 --- a/v2.0/src/samples/getuser-1.xml +++ b/v2.0/src/samples/getuser-1.xml @@ -1,13 +1,11 @@ - + - - + \ No newline at end of file diff --git a/v2.0/src/samples/identity_fault.xml b/v2.0/src/samples/identity_fault.xml index db480d9a..47457ad4 100644 --- a/v2.0/src/samples/identity_fault.xml +++ b/v2.0/src/samples/identity_fault.xml @@ -1,6 +1,5 @@ - - Fault -
Error Details...
- + + Fault +
Error Details...
+ \ No newline at end of file diff --git a/v2.0/src/section_identity-concepts.xml b/v2.0/src/section_identity-concepts.xml index c0510fd5..e376adb5 100644 --- a/v2.0/src/section_identity-concepts.xml +++ b/v2.0/src/section_identity-concepts.xml @@ -1,7 +1,9 @@
Identity concepts To use OpenStack Identity, you must be familiar with these