a47eba6e4c
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
492 lines
29 KiB
XML
492 lines
29 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter [<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
|
<!ENTITY HEAD '<command xmlns="http://docbook.org/ns/docbook">HEAD</command>'>
|
|
|
|
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="images/Check_mark_23x20_02.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
<!ENTITY CODES 'Normal response code(s):'>
|
|
<!ENTITY ERROR_CODES 'Error response code(s):'>
|
|
<!ENTITY NO_REQUEST '<para xmlns="http://docbook.org/ns/docbook">
|
|
This operation does not require a request body.</para>'>
|
|
<!ENTITY LONG_URI_REFHEAD '
|
|
<thead xmlns="http://docbook.org/ns/docbook">
|
|
<tr>
|
|
<td colspan="1">Verb</td>
|
|
<td colspan="4">URI</td>
|
|
<td colspan="3">Description</td>
|
|
</tr>
|
|
</thead>'>
|
|
<!ENTITY URI_REFHEAD '
|
|
<thead xmlns="http://docbook.org/ns/docbook">
|
|
<tr>
|
|
<td colspan="1">Verb</td>
|
|
<td colspan="1">URI</td>
|
|
<td colspan="4">Description</td>
|
|
</tr>
|
|
</thead>'>
|
|
]>
|
|
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0" xml:id="general-api-information">
|
|
<title>General API information</title>
|
|
<para>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.</para>
|
|
<xi:include href="section_identity-concepts.xml"/>
|
|
<section xml:id="Request_Response_Types-d1e459">
|
|
<title>Request and response formats</title>
|
|
<para>The OpenStack Identity API supports both JSON and XML data serialization request and
|
|
response formats.</para>
|
|
<para>Use the <code>Content-Type</code> request header to specify the request format. This
|
|
header is required for operations that have a request body.</para>
|
|
<para>The syntax for the <code>Content-Type</code> header is:</para>
|
|
<programlisting>Content-Type: application/<replaceable>FORMAT</replaceable></programlisting>
|
|
<para>Where <replaceable>FORMAT</replaceable> is either <literal>json</literal> or
|
|
<literal>xml</literal>.</para>
|
|
<para>Use one of the following methods to specify the response format:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><code>Accept</code> header</term>
|
|
<listitem>
|
|
<para>The syntax for the <code>Accept</code> header is:</para>
|
|
<programlisting>Accept: application/<replaceable>FORMAT</replaceable></programlisting>
|
|
<para>Where <replaceable>FORMAT</replaceable> is either <literal>json</literal>
|
|
or <literal>xml</literal>. The default format is
|
|
<literal>json</literal>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Query extension</term>
|
|
<listitem>
|
|
<para>Add an <literal>.xml</literal> or <literal>.json</literal> extension to
|
|
the request URI. For example, the <literal>.xml</literal> extension in the
|
|
following list servers URI request specifies that the response body is to be
|
|
returned in XML format:</para>
|
|
<programlisting>&GET; <replaceable>publicURL</replaceable>/servers.xml</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>If you do not specify a response format, JSON is the default.</para>
|
|
<para>If the <code>Accept</code> header and the query extension specify conflicting formats,
|
|
the format specified in the query extension takes precedence. For example, if the query
|
|
extension is <literal>.xml</literal> and the <code>Accept</code> header specifies
|
|
<literal>application/json</literal>, the response is returned in XML format.</para>
|
|
<para>You can serialize a response in a different format from the request format.</para>
|
|
<para><xref linkend="json-request"/> shows a request body in JSON format and <xref
|
|
linkend="xml-response"/> shows a response body in XML format.</para>
|
|
<example xml:id="json-request">
|
|
<title>Request with headers: JSON</title>
|
|
<programlisting language="http"><xi:include href="samples/samplerequestheader.txt" parse="text"/></programlisting>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/auth_credentials.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para><xref linkend="xml-response"/> shows the headers and XML response returned by the JSON
|
|
request:</para>
|
|
<example xml:id="xml-response">
|
|
<title>Response with headers: XML</title>
|
|
<programlisting language="http"><xi:include href="samples/sampleresponseheader.txt" parse="text"/></programlisting>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/auth.xml" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Content_Compression-d1e262">
|
|
<title>Content compression</title>
|
|
<para>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 <code>Accept-Encoding</code> header on the request from the client and indicated by
|
|
the <code>Content-Encoding</code> header in the server response. Unless the header is
|
|
explicitly set, encoding defaults to disabled.</para>
|
|
<table rules="all">
|
|
<caption>Compression headers</caption>
|
|
<thead>
|
|
<tr>
|
|
<td>Header type</td>
|
|
<td>Name</td>
|
|
<td>Value</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>HTTP/1.1 Request</td>
|
|
<td>Accept-Encoding</td>
|
|
<td>gzip</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HTTP/1.1 Response</td>
|
|
<td>Content-Encoding</td>
|
|
<td>gzip</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<section xml:id="Paginated_Collections-d1e325">
|
|
<title>Paginated collections</title>
|
|
<para>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 <parameter>limit</parameter> and
|
|
<parameter>marker</parameter> parameters in the URI. For example,
|
|
?<parameter>limit</parameter>=100&<parameter>marker</parameter>=1234. The
|
|
<parameter>marker</parameter> 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 <parameter>limit</parameter> parameter sets the page size. Both
|
|
parameters are optional. If the client requests a <parameter>limit</parameter> beyond
|
|
that which is supported by the deployment an <errorname>overLimit</errorname>
|
|
(<errorcode>413</errorcode>) fault might be thrown. A marker with an invalid ID
|
|
returns an <errorname>itemNotFound</errorname> (<errorcode>404</errorcode>)
|
|
fault.</para>
|
|
<note>
|
|
<para>Paginated collections never return itemNotFound (<errorcode>404</errorcode>)
|
|
faults when the collection is empty — clients should expect an empty
|
|
collection.</para>
|
|
</note>
|
|
<para>For convenience, collections contain atom "next" and "previous" links. The first page
|
|
in the list does not contain a <literal>previous</literal> link, the last page in the
|
|
list does not contain a <literal>next</literal> link. The following examples illustrate
|
|
three pages in a collection of tenants. The first page was retrieved through a &GET; to
|
|
<literal>http://identity.api.openstack.org/v2.0/1234/tenants?limit=1</literal>. In
|
|
these examples, the <parameter>limit</parameter> parameter sets the page size to a
|
|
single item. Subsequent <literal>next</literal> and <literal>previous</literal> links
|
|
honor the initial page size. Thus, a client might follow links to traverse a paginated
|
|
collection without having to input the <parameter>marker</parameter> parameter.</para>
|
|
<example>
|
|
<title>Tenant collection, first page: XML response</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/tenants-1.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Tenant collection, first page: JSON response</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/tenants-1.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Tenant collection, second page: XML response</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/tenants-2.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Tenant collection, second page: JSON response</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/tenants-2.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Tenant collection, last page: XML response</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/tenants-3.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Tenant collection, last page: JSON response</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/tenants-3.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>In the JSON representation, paginated collections contain a
|
|
<property>values</property> property that contains the items in the collections.
|
|
Links are accessed via the <property>links</property> 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.</para>
|
|
<example>
|
|
<title>Paginated roles in user: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/getuser-1.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Paginated roles in user: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/getuser-1.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Versions-d1e472">
|
|
<title>Versions</title>
|
|
<para>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 <code>Accept</code> or
|
|
<code>Content-Type</code> 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.</para>
|
|
<example>
|
|
<title>Request with MIME type versioning</title>
|
|
<literallayout class="monospaced">GET /tenants HTTP/1.1
|
|
Host: identity.api.openstack.org
|
|
Accept: application/vnd.openstack.identity+xml;version=1.1
|
|
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
|
|
</example>
|
|
<example>
|
|
<title>Request with URI versioning</title>
|
|
<literallayout class="monospaced">GET /v1.1/tenants HTTP/1.1
|
|
Host: identity.api.openstack.org
|
|
Accept: application/xml
|
|
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
|
|
</example>
|
|
<note>
|
|
<para>The MIME type versioning approach allows for the creation of permanent links,
|
|
because the version scheme is not specified in the URI path:
|
|
<literal>https://api.identity.openstack.org/tenants/12234</literal>.</para>
|
|
</note>
|
|
<para>If a request is made without a version specified in the URI or through HTTP headers, a
|
|
multiple-choices response (<returnvalue>300</returnvalue>) provides links and MIME types
|
|
to available versions.</para>
|
|
<example>
|
|
<title>Multiple choices: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/choices.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Multiple choices: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/choices.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>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 <code>DEPRECATED</code>. Providers should work with developers and
|
|
partners to ensure adequate migration time to the new version before deprecated versions
|
|
are discontinued.</para>
|
|
<para>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 <code>Accept</code>
|
|
header containing application/atom+xml or by adding a .atom to the request URI. This
|
|
enables standard Atom clients to track version changes.</para>
|
|
<example>
|
|
<title>List versions: HTTP request</title>
|
|
<literallayout class="monospaced">GET HTTP/1.1
|
|
Host: identity.api.openstack.org</literallayout>
|
|
</example>
|
|
<simpara>&CODES;<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue></simpara>
|
|
<simpara>&ERROR_CODES; badRequest (<errorcode>400</errorcode>), identityFault
|
|
(<errorcode>500</errorcode>),
|
|
serviceUnavailable(<errorcode>503</errorcode>)</simpara> &NO_REQUEST; <example>
|
|
<title>List versions: XML response</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/versions.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List versions: JSON response</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/versions.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>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 <returnvalue>302</returnvalue> 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.</para>
|
|
<example>
|
|
<title>Get version details: HTTP request</title>
|
|
<literallayout class="monospaced">
|
|
GET HTTP/1.1
|
|
Host: identity.api.openstack.org/v1.1/
|
|
</literallayout>
|
|
</example>
|
|
<simpara>&CODES;<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue></simpara>
|
|
<simpara>&ERROR_CODES; badRequest (<errorcode>400</errorcode>), identityFault
|
|
(<errorcode>500</errorcode>),
|
|
serviceUnavailable(<errorcode>503</errorcode>)</simpara> &NO_REQUEST; <example>
|
|
<title>Get version details: XML response</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/version.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Get version details: JSON response</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/version.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>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).</para>
|
|
<note>
|
|
<para>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.</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="Extensions-d1e688">
|
|
<title>Extensions</title>
|
|
<para>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.</para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<td colspan="1">Verb</td>
|
|
<td colspan="2">URI</td>
|
|
<td colspan="3">Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1">&GET;</td>
|
|
<td colspan="2">/extensions</td>
|
|
<td colspan="3">Returns a list of available extensions</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<simpara>&CODES;<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue></simpara>
|
|
<simpara>&ERROR_CODES; badRequest (<errorcode>400</errorcode>), identityFault
|
|
(<errorcode>500</errorcode>),
|
|
serviceUnavailable(<errorcode>503</errorcode>)</simpara> &NO_REQUEST; <para>Each
|
|
extension is identified by two unique identifiers, a <property>namespace</property> and
|
|
an <property>alias</property>. Additionally an extension contains documentation links in
|
|
various formats.</para>
|
|
<example>
|
|
<title>List extensions: XML response</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/extensions.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List extensions: JSON response</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/extensions.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>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 <errorname>itemNotFound</errorname> (<errorcode>404</errorcode>)
|
|
response.</para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<td colspan="1">Verb</td>
|
|
<td colspan="2">URI</td>
|
|
<td colspan="3">Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1">&GET;</td>
|
|
<td colspan="2">/extensions/<parameter>alias</parameter></td>
|
|
<td colspan="3">Return details of a single extension</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<simpara>&CODES;<returnvalue>200</returnvalue>, <returnvalue>203</returnvalue></simpara>
|
|
<simpara>&ERROR_CODES; itemNotFound (<errorcode>404</errorcode>), badRequest
|
|
(<errorcode>400</errorcode>), identityFault (<errorcode>500</errorcode>),
|
|
serviceUnavailable(<errorcode>503</errorcode>)</simpara> &NO_REQUEST; <example>
|
|
<title>Show extension details: XML response</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/extension.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Show extension details: JSON response</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/identity-api/src/v2.0/samples/extension.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>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 <xref linkend="UserEXT" xrefstyle="template: Examples %n"/> and
|
|
<xref linkend="UserEXTJ" xrefstyle="select: labelnumber"/> is defined in the
|
|
<code>RS-META</code> namespace. Extended headers are always prefixed with
|
|
<code>X-</code> followed by the alias and a dash: (<code>X-RS-META-HEADER1</code>).
|
|
Parameters must be prefixed with the extension alias followed by a colon.</para>
|
|
<important>
|
|
<para>Applications should ignore response data that contains extension elements. Also,
|
|
applications should also verify that an extension is available before submitting an
|
|
extended request.</para>
|
|
</important>
|
|
<example xml:id="UserEXT">
|
|
<title>Show user details: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/ext-getuser.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example xml:id="UserEXTJ">
|
|
<title>Show user details: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/ext-getuser.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Faults-d1e908">
|
|
<title>Faults</title>
|
|
<para>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.</para>
|
|
<example>
|
|
<title>Identity fault: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/identity_fault.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Identity fault: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/identity_fault.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>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).</para>
|
|
<para>The root element of the fault (for example, <errorname>identityFault</errorname>)
|
|
might change depending on the type of error. The following is an example of an
|
|
<errorname>itemNotFound</errorname> error.</para>
|
|
<example>
|
|
<title>itemNotFound fault: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/item_not_found.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>itemNotFound fault: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/item_not_found.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>The following table shows the possible fault types with associated error codes:</para>
|
|
<table rules="all">
|
|
<caption>Fault types</caption>
|
|
<thead>
|
|
<tr>
|
|
<th>Fault element</th>
|
|
<th>Associated error code</th>
|
|
<th>Expected in all requests</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr align="center">
|
|
<td>identityFault</td>
|
|
<td>500, 400</td>
|
|
<td> &CHECK; </td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>serviceUnavailable</td>
|
|
<td>503</td>
|
|
<td> &CHECK; </td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>badRequest</td>
|
|
<td>400</td>
|
|
<td> &CHECK; </td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>unauthorized</td>
|
|
<td>401</td>
|
|
<td> &CHECK; </td>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>overLimit</td>
|
|
<td>413</td>
|
|
<td/>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>userDisabled</td>
|
|
<td>403</td>
|
|
<td/>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>forbidden</td>
|
|
<td>403</td>
|
|
<td/>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>itemNotFound</td>
|
|
<td>404</td>
|
|
<td/>
|
|
</tr>
|
|
<tr align="center">
|
|
<td>tenantConflict</td>
|
|
<td>409</td>
|
|
<td/>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<para>From an XML schema perspective, all API faults are extensions of the base
|
|
<errorname>identityFault</errorname> fault type. When working with a system that
|
|
binds XML to actual classes (such as JAXB), one should be capable of using
|
|
<errorname>identityFault</errorname> as a “catch-all” if there's no interest in
|
|
distinguishing between individual fault types.</para>
|
|
</section>
|
|
</chapter>
|