From bde59e78a37d7af18b6ca85491ee50e367b2750f Mon Sep 17 00:00:00 2001 From: Ziad Sawalha Date: Thu, 26 May 2011 01:40:34 -0500 Subject: API Spec updates --- docs/guide/src/docbkx/identitydevguide.xml | 2902 +++++++++++++++------------- 1 file changed, 1566 insertions(+), 1336 deletions(-) (limited to 'docs/guide') diff --git a/docs/guide/src/docbkx/identitydevguide.xml b/docs/guide/src/docbkx/identitydevguide.xml index 78717a76..e38ecc51 100644 --- a/docs/guide/src/docbkx/identitydevguide.xml +++ b/docs/guide/src/docbkx/identitydevguide.xml @@ -1,42 +1,42 @@ - - - + + + - - GET'> - PUT'> - POST'> - DELETE'> + + GET'> + PUT'> + POST'> + DELETE'> - - - - - '> - - - - This operation does not require a request body.'> - - - Verb - URI - Description - - '> - - - Verb - URI - Description - - '> + + + + + '> + + + + This operation does not require a request body.'> + + + Verb + URI + Description + + '> + + + Verb + URI + Description + + '> ]> Keystone Developer Guide - - - - - - - OpenStack - - - - 2010 - 2011 - OpenStack - - API v2.0 - Keystone - OpenStack Identity - 2011-04-23 - - - Copyright details are filled in by the template. - - - - - This document is intended for software developers interested - in developing applications which utilize the Cloud Identity - Service for authentication. This document also includes - details on how to integrate services with the Cloud Identity - Service. - - + + + + + + + OpenStack + + + + 2010 + 2011 + OpenStack + + API v2.0 + Keystone - OpenStack Identity + 2011-04-23 + + + Copyright details are filled in by the template. + + + + + This document is intended for software developers interested + in developing applications which utilize the Cloud Identity + Service for authentication. This document also includes + details on how to integrate services with the Cloud Identity + Service. + + - Overview - - The Keystone Identity Service allows applications to obtain - tokens that can be used to access OpenStack resources. This - document is intended for software developers interested in - developing applications which utilize the Cloud Identity - Service for authentication. This document also includes - details on how to integrate services with the Cloud Identity - Service. - - - This Guide assumes the reader is familiar with RESTful web - services, HTTP/1.1, and JSON and/or XML serialization formats. - + Overview + + The Keystone Identity Service allows applications to obtain + tokens that can be used to access OpenStack resources. This + document is intended for software developers interested in + developing applications which utilize the Cloud Identity + Service for authentication. This document also includes + details on how to integrate services with the Cloud Identity + Service. + + + This Guide assumes the reader is familiar with RESTful web + services, HTTP/1.1, and JSON and/or XML serialization formats. + - Concepts - - The Keystone Identity Service has several key concepts that are - important to understand: - -
- Token - - A token is an arbitrary bit of text that is used to access - resources. Each token has a scope which describes which - resources are accessible with it. A token may be - revoked at anytime and is valid for a finite duration. - -
-
- Tenant - - Depending on the operator, a tenant may map to a customer, - account, organization, or project. - -
-
- User - - Users have a login and may be assigned tokens to access - resources. - -
-
- Role - - A role that an identity is associated with that allows it - to perform certain operations. Roles are managed by services - and operators. Tenant administrators may assign roles to users. - -
-
- Group - - A group of users. Global groups are managed by - operators. They are used to organize and assign privileges - to a group of related users. For example, an operator may - create a "delinquent" group, which will assign limited - privileges to users who have past due bills. - -
+ Concepts + + The Keystone Identity Service has several key concepts that are + important to understand: + +
+ Token + + A token is an arbitrary bit of text that is used to access + resources. Each token has a scope which describes which + resources are accessible with it. A token may be + revoked at anytime and is valid for a finite duration. + +
+
+ Tenant + + Depending on the operator, a tenant may map to a customer, + account, organization, or project. + +
+
+ User + + Users have a login and may be assigned tokens to access + resources. + + + This is a Rackspace extensions to support a local identity store. + Extending this to work on any backing store is out of scope. + +
+
+ Role + + A role that an identity is associated with that allows it + to perform certain operations. Roles are managed by services + and operators. Tenant administrators may assign roles to users. + +
+
+ Group + + A group of users. Global groups are managed by + operators. They are used to organize and assign privileges + to a group of related users. For example, an operator may + create a "delinquent" group, which will assign limited + privileges to users who have past due bills. + +
- General API Information - The Keystone API is implemented using a RESTful web service interface. All requests to - authenticate and operate against the Keystone API are performed using SSL over HTTP (HTTPS) on TCP - port 443. -
- Request/Response Types - The Keystone 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 - + General API Information + The Keystone API is implemented using a RESTful web service interface. All requests to + authenticate and operate against the Keystone API are performed using SSL over HTTP (HTTPS) on TCP + port 443. +
+ Request/Response Types + The Keystone 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 + - + - - - XML Response with Headers - + + + XML Response with Headers + - + - -
-
- Content Compression - Request and response body data my 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. - - - - - - - - - - - - - - - - - - - - - -
Compression Headers
Header TypeNameValue
HTTP/1.1 RequestAccept-Encodinggzip
HTTP/1.1 ResponseContent-Encodinggzip
-
-
- Paginated Collections - - To reduce load on the service, list operations will - return a maximum number of items at a time. The - maximum number of items returned is determined by the - IDM provider. To navigate the collection, the - parameters limit and - marker can be set in the URI - (e.g.?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 may be thrown. A - marker with an invalid ID will return an itemNotFound - (404) fault. - - - - 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 via 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 may follow links to - traverse a paginated collection without having to - input the marker parameter. - - - Tenant Collection, First Page: XML - + +
+
+ Content Compression + Request and response body data my 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. + + + + + + + + + + + + + + + + + + + + + +
Compression Headers
Header TypeNameValue
HTTP/1.1 RequestAccept-Encodinggzip
HTTP/1.1 ResponseContent-Encodinggzip
+
+
+ Paginated Collections + + To reduce load on the service, list operations will + 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, the + parameters limit and + marker can be set in the URI + (e.g.?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 may be thrown. A + marker with an invalid ID will return an itemNotFound + (404) fault. + + + + 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 via 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 may follow links to + traverse a paginated collection without having to + input the marker parameter. + + + Tenant Collection, First Page: XML + - - - - Tenant Collection, First Page: JSON - - - - Tenant Collection, Second Page: XML - + + + + Tenant Collection, First Page: JSON + + + + Tenant Collection, Second Page: XML + - - - - Tenant Collection, Second Page: JSON - - - - Tenant Collection, Last Page: XML - + + + + Tenant Collection, Second Page: JSON + + + + Tenant Collection, Last Page: XML + - - - - Tenant Collection, Last Page: JSON - - - - 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 grups are presented within a - user. Clients must follow the "next" link to continue to - retrive additonal groups belonging to a user. - - - Paginated Groups in a User: XML - + + + + Tenant Collection, Last Page: JSON + + + + 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 grups are presented within a + user. Clients must follow the "next" link to continue to + retrive additonal groups belonging to a user. + + + Paginated Groups in a User: XML + - - - - Paginated Groups in an User: JSON - - -
-
- 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 (e.g. 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 identifies the version - (application/vnd.openstack.identity-v1.1+xml). 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 - + + + + Paginated Groups in an User: JSON + + +
+
+ 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 (e.g. 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 identifies the version + (application/vnd.openstack.identity-v1.1+xml). 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 Host: identity.api.openstack.org Accept: application/vnd.openstack.identity-v1.1+xml X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - - Request with URI versioning - + + + + Request with URI versioning + GET /v1.1/tenants HTTP/1.1 Host: identity.api.openstack.org Accept: application/xml X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb - - - - - The MIME type versioning approach allows for the - creating 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. - - - Multiple Choices Response: XML - + + + + + The MIME type versioning approach allows for the + creating 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. + + + Multiple Choices Response: XML + - - - - Multiple Choices Response: JSON - - - - 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 (i.e. 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. - - - Versions List Request - + + + + Multiple Choices Response: JSON + + + + 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 (i.e. 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. + + + Versions List Request + GET HTTP/1.1 Host: identity.api.openstack.org - - - &CODES;200, 203 - &ERROR_CODES; badRequest - (400), identityFault - (500), - serviceUnavailable(503) - &NO_REQUEST; - - Versions List Response: XML - + + + &CODES;200, 203 + &ERROR_CODES; badRequest + (400), identityFault + (500), + serviceUnavailable(503) + &NO_REQUEST; + + Versions List Response: XML + - - - - Versions List Response: Atom - + + + + Versions List Response: Atom + - - - - Versions List Response: JSON - - - - You can also obtain additional information about a - specific version by performing a &GET; on the base - version URL - (e.g. https://identity.api.openstack.org/v1.1/). - Version request URLs should always end with a trailing - slash (/). If the slash is omitted, the server may - respond with a 302 - redirection request. Format extensions may be placed - after the slash - (e.g. 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. - - - Version Details Request - + + + + Versions List Response: JSON + + + + You can also obtain additional information about a + specific version by performing a &GET; on the base + version URL + (e.g. https://identity.api.openstack.org/v1.1/). + Version request URLs should always end with a trailing + slash (/). If the slash is omitted, the server may + respond with a 302 + redirection request. Format extensions may be placed + after the slash + (e.g. 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. + + + Version Details Request + GET HTTP/1.1 Host: identity.api.openstack.org/v1.1/ - - - &CODES;200, 203 - &ERROR_CODES; badRequest - (400), identityFault - (500), - serviceUnavailable(503) - &NO_REQUEST; - - Version Details Response: XML - + + + &CODES;200, 203 + &ERROR_CODES; badRequest + (400), identityFault + (500), + serviceUnavailable(503) + &NO_REQUEST; + + Version Details Response: XML + - - - - Version Details Response: Atom - + + + + Version Details Response: Atom + - - - - Version Details Response: JSON - - - - 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. - -
-
- 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 may not be available in - another. - - - - - Verb - URI - Description - - - - - &GET; - /extensions - Returns a list of available extensions - - - - &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. - - - Extensions Response: XML - + + + + Version Details Response: JSON + + + + 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. + +
+
+ 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 may not be available in + another. + + + + + Verb + URI + Description + + + + + &GET; + /extensions + Returns a list of available extensions + + + + &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. + + + Extensions Response: XML + - - - - Extensions Response: JSON - - - - Extensions may 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. - - - - - Verb - URI - Description - - - - - &GET; - /extensions/alias - Return details of a single extension - - - - &CODES;200, 203 - &ERROR_CODES; itemNotFound - (404), badRequest - (400), identityFault - (500), - serviceUnavailable(503) - &NO_REQUEST; - - Extension Response: xml - + + + + Extensions Response: JSON + + + + Extensions may 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. + + + + + Verb + URI + Description + + + + + &GET; + /extensions/alias + Return details of a single extension + + + + &CODES;200, 203 + &ERROR_CODES; itemNotFound + (404), badRequest + (400), identityFault + (500), + serviceUnavailable(503) + &NO_REQUEST; + + Extension Response: xml + - - - - Extensions Response: JSON - - - - Extensions may define new data types, parameters, actions, - headers, states, and resources. In XML, additional - elements and attributes may 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. - - - - Extended User Response: XML - + + + + Extensions Response: JSON + + + + Extensions may define new data types, parameters, actions, + headers, states, and resources. In XML, additional + elements and attributes may 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. + + + + Extended User Response: XML + - - - - Extended User Response: JSON - - -
-
- Faults - When an error occurs the system will return an HTTP error response code denoting the - type of error. The system will also return additional information about the fault in the - body of the response. - - XML Fault Response - + + + + Extended User Response: JSON + + +
+
+ Faults + When an error occurs the system will return an HTTP error response code denoting the + type of error. The system will also return additional information about the fault in the + body of the response. + + XML Fault Response + - - - JSON Fault Response - + + + JSON Fault 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 may contain - useful information for tracking down an error (e.g a stack trace). - The root element of the fault (e.g. identityFault) may change depending on the type of error. - The following is an example of an itemNotFound error. - - XML Not Found Fault - + + 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 may contain + useful information for tracking down an error (e.g a stack trace). + The root element of the fault (e.g. identityFault) may change depending on the type of error. + The following is an example of an itemNotFound error. + + XML Not Found Fault + - - - JSON Not Found Fault - + + + JSON Not Found Fault + - - The following is a list of possible fault types along with their associated error - codes. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Fault Types
Fault ElementAssociated Error CodeExpected in All Requests
identityFault500, 400 ✓
serviceUnavailable503 ✓
badRequest400 ✓
unauthorized401 ✓
overLimit413 -
userDisabled403 -
forbidden403 -
itemNotFound404 -
tenantConflict409 -
- 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. -
+ + The following is a list of possible fault types along with their associated error + codes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Fault Types
Fault ElementAssociated Error CodeExpected in All Requests
identityFault500, 400 ✓
serviceUnavailable503 ✓
badRequest400 ✓
unauthorized401 ✓
overLimit413 +
userDisabled403 +
forbidden403 +
itemNotFound404 +
tenantConflict409 +
+ 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. +
- Service Developer Operations -
- Overview - The operations described in this chapter allow service developers to get and validate - access tokens, manage users, and manage tenants. -
-
- Token Operations -
- Authenticate - - &URI_REFHEAD; - - - &POST; - /tokens - Authenticate to generate a token. - - - - &CODES;200, 203 - &ERROR_CODES; unauthorized (401), userDisabled - (403), badRequest (400), identityFault - (500), serviceUnavailable(503) - - TenantID is optional and may be used to specify that a - token should be returned that has access for resources - that particular tenant. - - - XML Auth Request - + Service API (Client Operations) +
+ Overview + The operations described in this chapter allow clients to authenticate and get + access tokens and endpoints. +
+
+ Core Service API Proposal + The following table of calls is proposed as code Keystone APIs + + &URI_REFHEAD; + + + &POST; + /tokens + Authenticate to generate a token. + + + &GET; + /tenants + Get a list of tenants accessible with suplied token. + + + + Any other Service APIs listed in this section will be extensions used for this + reference implementation of Keystone +
+ +
+ Authenticate + + &URI_REFHEAD; + + + &POST; + /tokens + Authenticate to generate a token. + + + + &CODES;200, 203 + &ERROR_CODES; unauthorized (401), userDisabled + (403), badRequest (400), identityFault + (500), serviceUnavailable(503) + + TenantID is optional and may be used to specify that a + token should be returned that has access to the resources + of that particular tenant. + + + XML Auth Request + - - - JSON Auth Request - + + + JSON Auth Request + - - - XML Auth Response - + + + XML Auth Response + - - - JSON Auth Response - + + + JSON Auth Response + - -
-
- Validate Token - - &LONG_URI_REFHEAD; - - - &GET; - /tokens/tokenId?belongsTo=tenantId - Check that a token is valid and that it belongs to a particular user - and return the permissions relevant to a particular client. - - - - &CODES;200, 203 - &ERROR_CODES; unauthorized (401), forbidden - (403), userDisabled(403), - badRequest (400), itemNotFound (404), - identityFault(500), - serviceUnavailable(503) - &NO_REQUEST; - - Valid tokens will exist in the - /tokens/tokenId path and invalid - tokens will not. In other words, a user should expect an - itemNotFound (404) fault for an - invalid token. - - - XML Validate Token Response - + +
+
+ Get Tenants + + &LONG_URI_REFHEAD; + + + &GET; + /tenants + Get a list of tenants. + + + + &CODES;200, 203 + &ERROR_CODES; unauthorized (401), + forbidden(403), overLimit(413), + badRequest (400), identityFault (500), + serviceUnavailable(503) + + The operation returns a list of tenants which the caller has + access to. + + &NO_REQUEST; + + XML Tenants Response + + + + + + JSON Tenants Response + + + + +
+ + + + + Admin API (Service Developer Operations) +
+ Overview + The operations described in this chapter allow service developers to get and validate + access tokens, manage users, and manage tenants. +
+
+ Core Admin API Proposal + The following table of calls is proposed as core Keystone Admin APIs +
+ Tokens + + &LONG_URI_REFHEAD; + + + &GET; + /tokens + Validate a token. + + + &DELETE; + /tokens/tokenId + Revoke an existing token. + + + +
+ +
+ Tenants + + &LONG_URI_REFHEAD; + + + &GET; + /tenants + Get a list of tenants. + + + &GET; + /tenants/tenantId + Get a tenant. + + + +
+ +
+ Endpoints (BaseURLs) + + &LONG_URI_REFHEAD; + + + &GET; + + /baseURLs?serviceName=ServiceName + + + Get a list of base URLs. + + + + &GET; + + /baseURLs/enabled?serviceName=ServiceName + + + Get a list of enabled base URLs. + + + + &GET; + + /baseURLs/baseURLId + + + Get a base URL. + + + + &GET; + + /tenants/tenantId/baseURLRefs + + + Get a list of base URLs for a tenant. + + + + &POST; + + /tenants/tenantId/baseURLRefs + + + Add a base URL to a tenant. + + + + &DELETE; + + /tenants/tenantId/baseURLRefs/baseURLId + + Remove Base URL from a tenant. + + + + +
+ +
+ Roles + + &LONG_URI_REFHEAD; + + + &GET; + + /roles + + Get a list of roles. + + + + &GET; + + /roles/roleId + + Get a a role. + + + + &GET; + + /users/userId/roleRefs + + + Get a list of roles for a user. + + + + &POST; + + /users/userId/roleRefs + + + Add a role to a user. + + + + &DELETE; + + /users/userId/roleRefs/roleRefId + + Remove a role from a user. + + + + +
+ All other APIs listed in this section will be extensions used for this + reference implementation of Keystone to support user and tenant management +
+
+ Token Operations +
+ Authenticate + All client operations are supported on the admin API +
+
+ Validate Token + + &LONG_URI_REFHEAD; + + + &GET; + /tokens/tokenId?belongsTo=tenantId + Check that a token is valid and that it belongs to a particular user + and return the permissions relevant to a particular client. + + + + &CODES;200, 203 + &ERROR_CODES; unauthorized (401), forbidden + (403), userDisabled(403), + badRequest (400), itemNotFound (404), + identityFault(500), + serviceUnavailable(503) + &NO_REQUEST; + + Valid tokens will exist in the + /tokens/tokenId path and invalid + tokens will not. In other words, a user should expect an + itemNotFound (404) fault for an + invalid token. + + + XML Validate Token Response + - - - JSON Validate Token Response - + + + JSON Validate Token Response + - -
-
- Revoke Token - - &LONG_URI_REFHEAD; - - - &DELETE; - /tokens/tokenId - Revoke an existing token. - - - - &CODES;204 - &ERROR_CODES; unauthorized (401), forbidden - (403), userDisabled(403), - badRequest (400), itemNotFound (404), - identityFault(500), - serviceUnavailable(503) - &NO_REQUEST; -
-
-
- Tenant Operations -
- Create a Tenant - - &LONG_URI_REFHEAD; - - - &POST; - /tenants - Create a tenant - - - - &CODES;201 - &ERROR_CODES; unauthorized (401), - forbidden(403), - badRequest (400), identityFault (500), - serviceUnavailable(503) - - XML Tenant Create Request - + +
+
+ Revoke Token + + &LONG_URI_REFHEAD; + + + &DELETE; + /tokens/tokenId + Revoke an existing token. + + + + &CODES;204 + &ERROR_CODES; unauthorized (401), forbidden + (403), userDisabled(403), + badRequest (400), itemNotFound (404), + identityFault(500), + serviceUnavailable(503) + &NO_REQUEST; +
+
+
+ Tenant Operations +
+ Create a Tenant + + &LONG_URI_REFHEAD; + + + &POST; + /tenants + Create a tenant + + + + &CODES;201 + &ERROR_CODES; unauthorized (401), + forbidden(403), + badRequest (400), identityFault (500), + serviceUnavailable(503) + + XML Tenant Create Request + - - - JSON Tenant Create Request - + + + JSON Tenant Create Request + - - - XML Tenant Create Response - + + + XML Tenant Create Response + - - - JSON Tenant Create Response - + + + JSON Tenant Create Response + - -
-
- Get Tenants - - &LONG_URI_REFHEAD; - - - &GET; - /tenants - Get a list of tenants. - - - - &CODES;200, 203 - &ERROR_CODES; unauthorized (401), - forbidden(403), overLimit(413), - badRequest (400), identityFault (500), - serviceUnavailable(503) - - The operation returns a list of tenants. The list may be - filtered to return only those tenants which the caller has - access to. - - &NO_REQUEST; - - XML Tenants Response - + +
+
+ Get Tenants + + &LONG_URI_REFHEAD; + + + &GET; + /tenants + Get a list of tenants. + + + + &CODES;200, 203 + &ERROR_CODES; unauthorized (401), + forbidden(403), overLimit(413), + badRequest (400), identityFault (500), + serviceUnavailable(503) + + The operation returns a list of tenants. The list may be + filtered to return only those tenants which the caller has + access to. + + &NO_REQUEST; + + XML Tenants Response + - - - JSON Tenants Response - + + + JSON Tenants Response + - -
-
- Get a Tenant - - &LONG_URI_REFHEAD; - - - &GET; - /tenants/tenantId - Get a tenant. - - - - &CODES;200, 203 - &ERROR_CODES; unauthorized (401), - forbidden(403), itemNotFound(404), - badRequest (400), identityFault (500), - serviceUnavailable(503) - &NO_REQUEST; - - XML Tenant Response - + +
+
+ Get a Tenant + + &LONG_URI_REFHEAD; + + + &GET; + /tenants/tenantId + Get a tenant. + + + + &CODES;200, 203 + &ERROR_CODES; unauthorized (401), + forbidden(403), itemNotFound(404), + badRequest (400), identityFault (500), + serviceUnavailable(503) + &NO_REQUEST; + + XML Tenant Response + - - - JSON Tenant Response - + + + JSON Tenant Response + - -
-
- Update a Tenant - - &LONG_URI_REFHEAD; - - - &PUT; - /tenants/tenantId - Update a tenant.. - - - - &CODES;200 - &ERROR_CODES; unauthorized (401), - forbidden(403), itemNotFound(404), - badRequest (400), identityFault (500), - serviceUnavailable(503) - - XML Tenant Update Request - + +
+
+ Update a Tenant + + &LONG_URI_REFHEAD; + + + &PUT; + /tenants/tenantId + Update a tenant.. + + + + &CODES;200 + &ERROR_CODES; unauthorized (401), + forbidden(403), itemNotFound(404), + badRequest (400), identityFault (500), + serviceUnavailable(503) + + XML Tenant Update Request + - - - JSON Tenant Update Request - + + + JSON Tenant Update Request + - - - XML Tenant Update Response - + + + XML Tenant Update Response + - - - JSON Tenant Update Response - + + + JSON Tenant Update Response + - -
-
- Delete a Tenant - - &LONG_URI_REFHEAD; - - - &DELETE; - /tenants/tenantId - Delete a Tenant. - - - - &CODES;204 - &ERROR_CODES; unauthorized (401), badRequest - (400), forbidden (403), itemNotFound - (404), identityFault (500), - serviceUnavailable(503) - &NO_REQUEST; -
-
-
- Base URLs -
- Get Base URLs - - &LONG_URI_REFHEAD; - - - &GET; - - /baseURLs?serviceName=ServiceName - - - Get a list of base URLs. - - - - &GET; - - /baseURLs/enabled?serviceName=ServiceName - - - Get a list of enabled base URLs. - - - - - - - &CODES; 200, - 203 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; - - Base URLs Response: XML - + +
+
+ Delete a Tenant + + &LONG_URI_REFHEAD; + + + &DELETE; + /tenants/tenantId + Delete a Tenant. + + + + &CODES;204 + &ERROR_CODES; unauthorized (401), badRequest + (400), forbidden (403), itemNotFound + (404), identityFault (500), + serviceUnavailable(503) + &NO_REQUEST; +
+
+
+ Base URLs +
+ Get Base URLs + + &LONG_URI_REFHEAD; + + + &GET; + + /baseURLs?serviceName=ServiceName + + + Get a list of base URLs. + + + + &GET; + + /baseURLs/enabled?serviceName=ServiceName + + + Get a list of enabled base URLs. + + + + + + + &CODES; 200, + 203 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; + + Base URLs Response: XML + - - - - Base URLs Response: JSON - + + + + Base URLs Response: JSON + - - -
-
- Get Base URL - - &LONG_URI_REFHEAD; - - - &GET; - - /baseURLs/baseURLId - - - Get a base URL. - - - - - - &CODES; 200, - 203 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; - - Base URL Response: XML - - + + +
+
+ Get Base URL + + &LONG_URI_REFHEAD; + + + &GET; + + /baseURLs/baseURLId + + + Get a base URL. + + + + + + &CODES; 200, + 203 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; + + Base URL Response: XML + + - - - - Base URL Response: JSON - - + + + + Base URL Response: JSON + + - - -
-
- Get Base URLs for a Tenant - - &LONG_URI_REFHEAD; - - - &GET; - - /tenants/tenantId/baseURLRefs - - - Get a list of base URLs for a tenant. - - - - - - &CODES; 200, - 203 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; - - Base URL Refs Response: XML - + + +
+
+ Get Base URLs for a Tenant + + &LONG_URI_REFHEAD; + + + &GET; + + /tenants/tenantId/baseURLRefs + + + Get a list of base URLs for a tenant. + + + + + + &CODES; 200, + 203 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; + + Base URL Refs Response: XML + - - - - Base URL Refs Response: JSON - + + + + Base URL Refs Response: JSON + - - -
-
- Add Base URL to a Tenant. - - &LONG_URI_REFHEAD; - - - &POST; - - /tenants/tenantId/baseURLRefs - - - Add a base URL to a tenant. - - - - - - &CODES; - 201 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - itemNotFound (404), - authFault (500), - serviceUnavailable (503) - - - Expect a badRequest (400) response if a disabled base URL is added or if the base URL had been previously added. - - - Add Base URL Request: XML - - + + +
+
+ Add Base URL to a Tenant. + + &LONG_URI_REFHEAD; + + + &POST; + + /tenants/tenantId/baseURLRefs + + + Add a base URL to a tenant. + + + + + + &CODES; + 201 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + itemNotFound (404), + authFault (500), + serviceUnavailable (503) + + + Expect a badRequest (400) response if a disabled base URL is added or if the base URL had been previously added. + + + Add Base URL Request: XML + + - - - - Add Base URL Request: JSON - - + + + + Add Base URL Request: JSON + + - - -
-
- Remove Base URLs from a Tennat - - &LONG_URI_REFHEAD; - - - &DELETE; - - /tenant/tenantId/baseURLRefs/baseURLId - - Remove Base URL from a user. - - - - - - &CODES; - 204 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - itemNotFound (404), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; -
-
- -
- Roles -
- Get roles - - &LONG_URI_REFHEAD; - - - &GET; - - /roles - - Get a list of roles. - - - - - - &CODES; 200, - 203 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; - - Roles Response: XML - + + +
+
+ Remove Base URLs from a Tennat + + &LONG_URI_REFHEAD; + + + &DELETE; + + /tenant/tenantId/baseURLRefs/baseURLId + + Remove Base URL from a tenant. + + + + + + &CODES; + 204 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + itemNotFound (404), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; +
+
+ +
+ Roles +
+ Get roles + + &LONG_URI_REFHEAD; + + + &GET; + + /roles + + Get a list of roles. + + + + + + &CODES; 200, + 203 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; + + Roles Response: XML + - - - - Roles Response: JSON - + + + + Roles Response: JSON + - - -
-
- Get Role - - &LONG_URI_REFHEAD; - - - &GET; - - /roles/roleId - - - Get a role. - - - - - - &CODES; 200, - 203 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; - - Role Response: XML - - + + +
+
+ Get Role + + &LONG_URI_REFHEAD; + + + &GET; + + /roles/roleId + + + Get a role. + + + + + + &CODES; 200, + 203 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; + + Role Response: XML + + - - - - Role Response: JSON - - + + + + Role Response: JSON + + - - -
-
- Get roles for a User - - &LONG_URI_REFHEAD; - - - &GET; - - /users/userId/roleRefs - - - Get a list of roles for a user. - - - - - - &CODES; 200, - 203 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; - - Role Refs Response: XML - + + +
+
+ Get roles for a User + + &LONG_URI_REFHEAD; + + + &GET; + + /users/userId/roleRefs + + + Get a list of roles for a user. + + + + + + &CODES; 200, + 203 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; + + Role Refs Response: XML + - - - - Role Refs Response: JSON - + + + + Role Refs Response: JSON + - - -
-
- Add Role to a User - - &LONG_URI_REFHEAD; - - - &POST; - - /users/userId/roleRefs - - - Add a role to a user. - - - - - - &CODES; - 201 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - itemNotFound (404), - authFault (500), - serviceUnavailable (503) - - - Add Role Request: XML - - + + +
+
+ Add Role to a User + + &LONG_URI_REFHEAD; + + + &POST; + + /users/userId/roleRefs + + + Add a role to a user. + + + + + + &CODES; + 201 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + itemNotFound (404), + authFault (500), + serviceUnavailable (503) + + + Add Role Request: XML + + - - - - Add Role Request: JSON - - + + + + Add Role Request: JSON + + - - -
-
- Remove roles from a User - - &LONG_URI_REFHEAD; - - - &DELETE; - - /users/userId/roleRefs/roleRefId - - Remove a role from a user. - - - - - - &CODES; - 204 - - - &ERROR_CODES; - unauthorized (401), - forbidden (403), - badRequest (400), - itemNotFound (404), - authFault (500), - serviceUnavailable (503) - - &NO_REQUEST; -
-
- + + +
+
+ Remove roles from a User + + &LONG_URI_REFHEAD; + + + &DELETE; + + /users/userId/roleRefs/roleRefId + + Remove a role from a user. + + + + + + &CODES; + 204 + + + &ERROR_CODES; + unauthorized (401), + forbidden (403), + badRequest (400), + itemNotFound (404), + authFault (500), + serviceUnavailable (503) + + &NO_REQUEST; +
+
-- cgit