[prev in list] [next in list] [prev in thread] [next in thread]
List: forgerock-openam-commit
Subject: [CommitOpenAM] [10297] trunk/openam/openam-documentation/openam-doc-source/src/main/docbkx
From: noreply () forgerock ! org
Date: 2014-08-28 16:14:42
Message-ID: 20140828161442.B4FDB422A4 () sources ! internal ! forgerock ! com
[Download RAW message or body]
[Attachment #2 (text/html)]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[10297] trunk/openam/openam-documentation/openam-doc-source/src/main/docbkx/dev-guide/chap-rest.xml: \
AME-4314 - CR-4336 - Update list of REST status codes to reflect recent \
fixes.</title> </head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: \
verdana,arial,helvetica,sans-serif; font-size: 10pt; } #msg dl a { font-weight: \
bold} #msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: \
bold; } #msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: \
6px; } #logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em \
0; } #logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg \
h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; } \
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; \
} #logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: \
-1.5em; padding-left: 1.5em; } #logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em \
1em 0 1em; background: white;} #logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid \
#fa0; border-bottom: 1px solid #fa0; background: #fff; } #logmsg table th { \
text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted \
#fa0; } #logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: \
0.2em 0.5em; } #logmsg table thead th { text-align: center; border-bottom: 1px solid \
#fa0; } #logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: \
6px; } #patch { width: 100%; }
#patch h4 {font-family: \
verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, \
#patch .copfile {border:1px solid #ccc;margin:10px 0;} #patch ins \
{background:#dfd;text-decoration:none;display:block;padding:0 10px;} #patch del \
{background:#fdd;text-decoration:none;display:block;padding:0 10px;} #patch .lines, \
.info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a \
href="http://sources.forgerock.org/changelog/openam/?cs=10297">10297</a></dd> \
<dt>Author</dt> <dd>chris.lee</dd> <dt>Date</dt> <dd>2014-08-28 17:14:42 +0100 (Thu, \
28 Aug 2014)</dd> </dl>
<h3>Log Message</h3>
<pre>AME-4314 - CR-4336 - Update list of REST status codes to reflect recent fixes. \
Updated the docs with a missing status code, and tweaked others to mention potential \
scenarios.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkopenamopenamdocumentationopenamdocsourcesrcmaindocbkxdevguidechapre \
stxml">trunk/openam/openam-documentation/openam-doc-source/src/main/docbkx/dev-guide/chap-rest.xml</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkopenamopenamdocumentationopenamdocsourcesrcmaindocbkxdevguidechaprestxml"></a>
<div class="modfile"><h4>Modified: \
trunk/openam/openam-documentation/openam-doc-source/src/main/docbkx/dev-guide/chap-rest.xml \
(10296 => 10297)</h4> <pre class="diff"><span>
<span class="info">--- \
trunk/openam/openam-documentation/openam-doc-source/src/main/docbkx/dev-guide/chap-rest.xml 2014-08-28 \
15:42:34 UTC (rev 10296)
+++ trunk/openam/openam-documentation/openam-doc-source/src/main/docbkx/dev-guide/chap-rest.xml 2014-08-28 \
16:14:42 UTC (rev 10297) </span><span class="lines">@@ -7466,8 +7466,7 @@
</span><span class="cx"> <para>OpenAM REST APIs respond to successful \
requests with HTTP status codes </span><span class="cx"> in the 2xx range. OpenAM \
REST APIs respond to error conditions with HTTP </span><span class="cx"> status \
codes in the 4xx and 5xx range. Status codes used are described in </span><del>- \
the
- following list.</para>
</del><ins>+ the following list.</para>
</ins><span class="cx">
</span><span class="cx"> <variablelist>
</span><span class="cx"> <varlistentry>
</span><span class="lines">@@ -7491,18 +7490,23 @@
</span><span class="cx"> <varlistentry>
</span><span class="cx"> <term>400 Bad Request</term>
</span><span class="cx"> <listitem>
</span><del>- <para>The request was malformed as in the following example, \
which is
- sending bad data in the payload for the action.</para>
</del><ins>+ <para>The request was malformed. Either parameters required \
by the + action were missing, or as in the following example incorrect data was
+ sent in the payload for the action.</para>
</ins><span class="cx">
</span><del>- <screen>
</del><ins>+<screen>
</ins><span class="cx"> $ <userinput>curl \
</span><span class="cx"> --request POST \
</span><span class="cx"> --header "Content-Type: application/json" \
</span><span class="cx"> --data '{"bad":"data"}' \
</span><del>- https://openam.example.com:8443/openam/json/users?_action=forgotPassword</userinput>
-
-<computeroutput>{"code":400,"reason":"Bad \
Request","message":"Username not \
provided"}</computeroutput>
- </screen>
</del><ins>+ https://openam.example.com:8443/openam/json/users?_action=forgotPassword
+</userinput>
+<computeroutput>{
+ "code":400,
+ "reason":"Bad Request",
+ "message":"Username or email not provided in request"
+}</computeroutput>
+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><span class="lines">@@ -7512,13 +7516,17 @@
</span><span class="cx"> <para>The request requires user authentication \
as in the following </span><span class="cx"> example, which is missing an SSO \
Token value.</para> </span><span class="cx">
</span><del>- <screen>
</del><ins>+<screen>
</ins><span class="cx"> $ <userinput>curl \
</span><span class="cx"> --request POST \
</span><del>- https://openam.example.com:8443/openam/json/sessions?_action=logout</userinput>
-
-<computeroutput>{ "code": 401, "reason": \
"Unauthorized", "message": "Access denied" \
}</computeroutput>
- </screen>
</del><ins>+ https://openam.example.com:8443/openam/json/sessions?_action=logout
+</userinput>
+<computeroutput>{
+ "code": 401,
+ "reason": "Unauthorized",
+ "message": "Access denied"
+}</computeroutput>
+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><span class="lines">@@ -7529,25 +7537,26 @@
</span><span class="cx"> following example, which has a regular user trying to \
read the OpenAM </span><span class="cx"> administrator profile.</para>
</span><span class="cx">
</span><del>- <screen>
</del><ins>+<screen>
</ins><span class="cx"> $ <userinput>curl \
</span><span class="cx"> --request POST \
</span><span class="cx"> --header "X-OpenAM-Username: demo" \
</span><span class="cx"> --header "X-OpenAM-Password: changeit" \
</span><del>- https://openam.example.com:8443/openam/json/authenticate</userinput>
-
</del><ins>+ https://openam.example.com:8443/openam/json/authenticate
+</userinput>
</ins><span class="cx"> <computeroutput>{ "tokenId": \
"AQIC5w...YyMA..*" }</computeroutput> </span><span class="cx">
</span><span class="cx"> $ <userinput>curl \
</span><span class="cx"> --header "iplanetDirectoryPro: AQIC5w...YyMA..*" \
\ </span><del>- https://openam.example.com:8443/openam/json/users/amadmin</userinput>
</del><ins>+ https://openam.example.com:8443/openam/json/users/amadmin
+</userinput>
</ins><span class="cx"> <computeroutput>{
</span><del>- "code": 403,
- "reason": "Forbidden",
- "message": "Permission to perform the read operation denied to
- id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
</del><ins>+ "code": 403,
+ "reason": "Forbidden",
+ "message": "Permission to perform the read operation denied to
+ id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
</ins><span class="cx"> }</computeroutput>
</span><del>- </screen>
</del><ins>+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><span class="lines">@@ -7557,13 +7566,17 @@
</span><span class="cx"> <para>The specified resource could not be found \
as in the following </span><span class="cx"> example, which is attempting to \
read a nonexistent user's profile.</para> </span><span class="cx">
</span><del>- <screen>
</del><ins>+<screen>
</ins><span class="cx"> $ <userinput>curl \
</span><span class="cx"> --header "iplanetDirectoryPro: AQIC5w...NTcy*" \
</span><del>- https://openam.example.com:8443/openam/json/users/missing</userinput>
-
-<computeroutput>{"code":404,"reason":"Not \
Found","message":"Resource cannot be \
found."}</computeroutput>
- </screen>
</del><ins>+ https://openam.example.com:8443/openam/json/users/missing
+</userinput>
+<computeroutput>{
+ "code":404,
+ "reason":"Not Found",
+ "message":"Resource cannot be found."
+}</computeroutput>
+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><span class="lines">@@ -7578,10 +7591,50 @@
</span><span class="cx"> <term>409 Conflict</term>
</span><span class="cx"> <listitem>
</span><span class="cx"> <para>The request would have resulted in a \
conflict with the current </span><del>- state of the resource.</para>
</del><ins>+ state of the resource. For example using the Forgot Password \
feature + and specifying the user's email address as in the following
+ example, where multiple users have the same email address.</para>
+
+<screen>
+$ <userinput>curl \
+ --request POST \
+ --header "Content-Type: application/json" \
+ --data '{"email":"demo@example.com"}' \
+ https://openam.example.com:8443/openam/json/users?_action=forgotPassword
+</userinput>
+<computeroutput>{
+ "code":409,
+ "reason":"Conflict",
+ "message":"Multiple users found"
+}</computeroutput>
+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><ins>+
+ <varlistentry>
+ <term>410 Gone</term>
+ <listitem>
+ <para>The requested resource is no longer available, and will not
+ become available again. The URI returned for resetting a password may
+ have expired as in the following example.</para>
+
+<screen>
+$ <userinput>curl \
+ --request POST \
+ --header "Content-Type: application/json" \
+ --data '{"username": "demo"}' \
+ https://openam.example.com:8443/openam/json/users/?_action=forgotPassword
+</userinput>
+<computeroutput>{
+ "code":410,
+ "reason":"Gone",
+ "message":"Token not found"
+}</computeroutput>
+</screen>
+ </listitem>
+ </varlistentry>
+
</ins><span class="cx"> <!-- Object versioning does not seem to be used in \
OpenAM REST. </span><span class="cx"> <varlistentry>
</span><span class="cx"> <term>412 Precondition Failed</term>
</span><span class="lines">@@ -7600,18 +7653,19 @@
</span><span class="cx"> to pass basic authentication credentials as \
form-encoded data rather than </span><span class="cx"> query string \
parameters.</para> </span><span class="cx">
</span><del>- <screen>
</del><ins>+<screen>
</ins><span class="cx"> $ <userinput>curl \
</span><span class="cx"> --request POST \
</span><span class="cx"> --data "username=demo&amp;password=changeit" \
\ </span><del>- https://openam.example.com:8443/openam/json/authenticate</userinput>
</del><ins>+ https://openam.example.com:8443/openam/json/authenticate
+</userinput>
</ins><span class="cx"> <computeroutput>...
</span><span class="cx"> HTTP Status 415
</span><span class="cx"> ...
</span><span class="cx"> The server refused this request because the request entity \
is in a </span><del>- format not supported by the requested resource for the \
requested method </del><ins>+format not supported by the requested resource for the \
requested method </ins><span class="cx"> ...</computeroutput>
</span><del>- </screen>
</del><ins>+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><span class="lines">@@ -7629,7 +7683,24 @@
</span><span class="cx"> <term>500 Internal Server Error</term>
</span><span class="cx"> <listitem>
</span><span class="cx"> <para>The server encountered an unexpected \
condition which prevented it </span><del>- from fulfilling the \
request.</para> </del><ins>+ from fulfilling the request. This could be \
caused by an invalid + configuration in the Email Service, or as in the \
following example the + specified user account not having an associated email \
address to send + the Forgot Password URI to.</para>
+
+<screen>
+$ <userinput>curl \
+ --request POST \
+ --header "Content-Type: application/json" \
+ --data '{"username": "demo"}' \
+ https://openam.example.com:8443/openam/json/users/?_action=forgotPassword
+</userinput>
+<computeroutput>{
+ "code":500,
+ "reason":"Internal Server Error",
+ "message":"No email provided in profile."
+}</computeroutput>
+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><span class="lines">@@ -7640,25 +7711,41 @@
</span><span class="cx"> the request as in the following example, which is \
attempting to delete </span><span class="cx"> an entry as a delete action \
instead of using an HTTP DELETE request.</para> </span><span class="cx">
</span><del>- <screen>
</del><ins>+<screen>
</ins><span class="cx"> $ <userinput>curl \
</span><span class="cx"> --request POST \
</span><span class="cx"> --header "iplanetDirectoryPro: AQIC5w...NTcy*" \
</span><del>- https://openam.example.com:8443/openam/json/users/demo?_action=delete</userinput>
-
</del><ins>+ https://openam.example.com:8443/openam/json/users/demo?_action=delete
+</userinput>
</ins><span class="cx"> <computeroutput>{
</span><del>- "code": 501,
- "reason": "Not Implemented",
- "message": "Actions are not supported for resource \
instances" </del><ins>+ "code": 501,
+ "reason": "Not Implemented",
+ "message": "Actions are not supported for resource instances"
</ins><span class="cx"> }</computeroutput>
</span><del>- </screen>
</del><ins>+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx">
</span><span class="cx"> <varlistentry>
</span><span class="cx"> <term>503 Service Unavailable</term>
</span><span class="cx"> <listitem>
</span><del>- <para>The requested resource was temporarily \
unavailable.</para> </del><ins>+ <para>The requested resource was \
temporarily unavailable. The + service may have been disabled, as in the \
following example, + where the Forgot Password functionality has been \
disabled.</para> +
+<screen>
+$ <userinput>curl \
+ --request POST \
+ --header "Content-Type: application/json" \
+ --data '{"username": "demo"}' \
+ https://openam.example.com:8443/openam/json/users/?_action=forgotPassword
+</userinput>
+<computeroutput>{
+ "code":503,
+ "reason":"Service Unavailable",
+ "message":"Forgot password is not accessible."
+}</computeroutput>
+</screen>
</ins><span class="cx"> </listitem>
</span><span class="cx"> </varlistentry>
</span><span class="cx"> </variablelist>
</span></span></pre>
</div>
</div>
<div id="footer">Copyright (c) by ForgeRock. All rights reserved.</div>
</body>
</html>
_______________________________________________
CommitOpenAM mailing list
CommitOpenAM@forgerock.org
https://lists.forgerock.org/mailman/listinfo/commitopenam
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic