diff --git a/openstack-identity-api/v3/src/markdown/identity-api-v3.md b/openstack-identity-api/v3/src/markdown/identity-api-v3.md index 8e92ab05..56a140d7 100644 --- a/openstack-identity-api/v3/src/markdown/identity-api-v3.md +++ b/openstack-identity-api/v3/src/markdown/identity-api-v3.md @@ -12,6 +12,8 @@ policy engine rule sets. What's New in Version 3.2 ------------------------- +These features are not yet considered stable (expected January 2014). + - Extension Discovery. - Introduced a mechanism to opt-out from catalog information during token validation. @@ -19,6 +21,8 @@ What's New in Version 3.2 What's New in Version 3.1 ------------------------- +These features are considered stable as of July 18, 2013. + - A token without an explicit scope of authorization is issued if the user does not specify a project and does not have authorization on the project specified by their default project attribute. @@ -31,6 +35,8 @@ What's New in Version 3.1 What's New in Version 3.0 ------------------------- +These features are considered stable as of February 20, 2013. + - Former "Service" and "Admin" APIs (including CRUD operations previously defined in the v2 OS-KSADM extension) are consolidated into a single core API - "Tenants" are now known as "projects" @@ -47,12 +53,64 @@ What's New in Version 3.0 - Partial updates are performed using the HTTP `PATCH` method - Token ID values no longer appear in URLs +Document Overview +----------------- + +This document is always evolving as new features are added, use cases are +clarified, etc. API features added since the original publication of this +document are summarized above, grouped by the API version in which they were +first introduced. This document is treated as the single source of truth for +the entire 3.x series of the API. + +A particular implementation of the API is never referenced by name. This is +documentation for the HTTP API itself. Details of the code-base servicing the +API, such as architecture, configuration, and deployment, are not relevant +here. + +The "API Conventions" section defines architectural patterns applied to the +entire API until a portion of the API documents an exception to the overall +conventions. Details of the conventions are not repeated throughout the +document, except in examples, so the reader is expected to have understood the +conventions before reading any further. The goal is to reduce the cost of +documentation maintenance (DRY) and improve self-consistency across the API, +which makes the API more intuitive to readers and fosters simpler +implementations. + +A high level overview of the resources presented by the API are documented in +the "API Resources" section, including required and optional attributes, use +cases and expected behaviors. Specific API calls are not enumerated, although +the feature set of the related calls should be described if it deviates from +the conventions used by the rest of the API (for example, a resource could be +constrained as "a read-only collection"). + +Finally, the specific calls supported by the API are enumerated with examples +at the end of the document. The examples are intended to be "realistic" +representations of actual requests and responses you could expect from an +implementation of the API. Specifically, the JSON should be syntactically valid +and use data that is self-consistent with related calls. + +The features described by this document are intended to be applicable to all +implementations of the API. If a particular implementation or deployment should +not be expected to have a use case for a particular feature, that feature +should be documented as an extension to this API. Extensions may suffix +existing resources with their own namespace in order to add new resources, or +prefix new attributes on existing resource representations. To clearly +distinguish extensions from the core API (which is described by this document) +and avoid namespace collisions between extensions, suffixes and prefixes are +composed of an uppercased abbreviation of the organization supporting the +extension (such as "OS" for OpenStack), followed by a hyphen ("-"), followed by +an uppercased abbreviation of the extension name (such as "OAUTH1" for OAuth +1.0). Therefore, an extension could be identified as "OS-OAUTH1". + API Conventions --------------- -The Identity API provides a RESTful JSON interface. +This section describes architectural patterns applied throughout the Identity +API, unless an exception to these conventions is specifically documented. In +general, the Identity API provides an HTTP interface using JSON as the primary +transport format. -Each REST resource contains a canonically unique identifier (ID) defined by the +Each resource contains a canonically unique identifier (ID) defined by the Identity service implementation and is provided as the `id` attribute; Resource ID's are strings of non-zero length. @@ -64,20 +122,20 @@ TCP port 35357 is designated by the Internet Assigned Numbers Authority responses in this document therefore assume that the Identity service implementation is deployed at the root of `http://identity:35357/`. +### Headers + +- `X-Auth-Token` + + This header is used to convey the API user's authentication token when + accessing Identity APIs. + +- `X-Subject-Token` + + This header is used to convey the subject of the request for token-related + operations. + ### Required Attributes -Headers: - - - `X-Auth-Token` - - This header is used to convey the authentication token when accessing - Identity APIs. - - - `X-Subject-Token` - - This header is used to convey the subject of the request for token-related - operations. - For collections: - `links` (object)