Skip to content

Commit 897e516

Browse files
technoweenietechnoweenie
committed
document new label stuff, and client errors
1 parent b04eabf commit 897e516

File tree

4 files changed

+80
-9
lines changed

4 files changed

+80
-9
lines changed

‎css/styles.css‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,9 +144,13 @@ dd + dd {
144144
padding: 1em 0;
145145
}
146146

147+
#content ul,
148+
#content ol {
149+
margin-left: 1em;
150+
}
151+
147152
#content ul {
148153
list-style-type: disc;
149-
margin-left: 1em;
150154
}
151155

152156
#footer-wrapper {

‎v3/index.html‎

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ <h1 id="api-v3">API v3</h1>
4646

4747
<ul>
4848
<li><a href="#schema">Schema</a></li>
49+
<li><a href="#client-errors">Client Errors</a></li>
4950
<li><a href="#http-verbs">HTTP Verbs</a></li>
5051
<li><a href="#authentication">Authentication</a></li>
5152
<li><a href="#pagination">Pagination</a></li>
@@ -76,7 +77,68 @@ <h1 id="api-v3">API v3</h1>
7677
<pre><code>YYYY-MM-DDTHH:MM:SSZ
7778
</code></pre>
7879

79-
<h2 id="http-verbs">HTTP Verbs</h2>
80+
<h2 id="client-errors">Client Errors</h2>
81+
82+
<p>There are three possible types of client errors on API calls that
83+
receive request bodies:</p>
84+
85+
<ol>
86+
<li>
87+
<p>Sending invalid JSON will result in a <code>400 Bad Request</code> response.</p>
88+
89+
<pre><code> HTTP/1.1 400 Bad Request
90+
Content-Length: 35
91+
92+
{"message":"Problems parsing JSON"}
93+
</code></pre>
94+
</li>
95+
<li>
96+
<p>Sending the wrong type of JSON values will result in a <code>400 Bad
97+
Request</code> response.</p>
98+
99+
<pre><code> HTTP/1.1 400 Bad Request
100+
Content-Length: 40
101+
102+
{"message":"Body should be a JSON Hash"}
103+
</code></pre>
104+
</li>
105+
<li>
106+
<p>Sending invalid files will result in a 422 Unprocessable Entity
107+
response.</p>
108+
109+
<pre><code> HTTP/1.1 422 Unprocessable Entity
110+
Content-Length: 149
111+
112+
{
113+
"message": "Validation Failed",
114+
"errors": [
115+
{
116+
"resource": "Issue",
117+
"field": "title",
118+
"code": "missing_field"
119+
}
120+
]
121+
}
122+
</code></pre>
123+
</li>
124+
</ol><p>All error objects have resource and field properties so that your client
125+
can tell what the problem is. There’s also an error code to let you
126+
know what is wrong with the field. These are the possible validation error
127+
codes:</p>
128+
129+
<dl>
130+
<dt>missing</dt>
131+
<dd>This means a resource does not exist.</dd>
132+
<dt>missing_field</dt>
133+
<dd>This means a required field on a resource has not been set.</dd>
134+
<dt>invalid</dt>
135+
<dd>This means the formatting of a field is invalid. The documentation
136+
for that resource should be able to give you more specific information.</dd>
137+
<dt>already_exists</dt>
138+
<dd>This means another resource has the same value as this field. This
139+
can happen in resources that must have some unique key (such as Label
140+
names).</dd>
141+
</dl><h2 id="http-verbs">HTTP Verbs</h2>
80142

81143
<p>Where possible, API v3 strives to use appropriate HTTP verbs for each
82144
action.</p>

‎v3/issues/index.html‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,8 @@ <h3 id="input">Input</h3>
150150
<pre class="highlight"><code class="language-javascript"><span class="p">{</span><span class="s2">"title"</span><span class="o">=&gt;</span><span class="s2">"String"</span><span class="p">,</span>
151151
<span class="s2">"body"</span><span class="o">=&gt;</span><span class="s2">"String"</span><span class="p">,</span>
152152
<span class="s2">"assignee"</span><span class="o">=&gt;</span><span class="s2">"String User login"</span><span class="p">,</span>
153-
<span class="s2">"milestone"</span><span class="o">=&gt;</span><span class="s2">"Integer Milestone number"</span><span class="p">}</span>
153+
<span class="s2">"milestone"</span><span class="o">=&gt;</span><span class="s2">"Integer Milestone number"</span><span class="p">,</span>
154+
<span class="s2">"labels"</span><span class="o">=&gt;</span><span class="p">[</span><span class="s2">"Label1"</span><span class="p">,</span> <span class="s2">"Label2"</span><span class="p">]}</span>
154155
</code></pre>
155156

156157
<h3 id="response-1">Response</h3>
@@ -312,10 +313,14 @@ <h3 id="input-1">Input</h3>
312313

313314
<pre class="highlight"><code class="language-javascript"><span class="p">{</span><span class="s2">"title"</span><span class="o">=&gt;</span><span class="s2">"String"</span><span class="p">,</span>
314315
<span class="s2">"body"</span><span class="o">=&gt;</span><span class="s2">"String"</span><span class="p">,</span>
315-
<span class="s2">"assignee"</span><span class="o">=&gt;</span><span class="s2">"String"</span><span class="p">,</span>
316-
<span class="s2">"milestone"</span><span class="o">=&gt;</span><span class="s2">"Integer"</span><span class="p">}</span>
316+
<span class="s2">"assignee"</span><span class="o">=&gt;</span><span class="s2">"String User login"</span><span class="p">,</span>
317+
<span class="s2">"milestone"</span><span class="o">=&gt;</span><span class="s2">"Integer Milestone number"</span><span class="p">,</span>
318+
<span class="s2">"labels"</span><span class="o">=&gt;</span><span class="p">[</span><span class="s2">"Label1"</span><span class="p">,</span> <span class="s2">"Label2"</span><span class="p">]}</span>
317319
</code></pre>
318320

321+
<p>Pass one or more Labels to <em>replace</em> the set of Labels on this Issue.
322+
Send an empty array (<code>[]</code>) to clear all Labels from the Issue.</p>
323+
319324
<h3 id="response-3">Response</h3>
320325

321326
<pre class="headers"><code>Status: 200 OK

‎v3/issues/labels/index.html‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -146,8 +146,7 @@ <h2 id="add-labels-to-an-issue">Add Labels to an Issue</h2>
146146
</code></pre>
147147

148148
<h3 id="input-2">Input</h3>
149-
150-
<pre class="highlight"><code class="language-javascript"><span class="p">[{</span><span class="s2">"name"</span><span class="o">=&gt;</span><span class="s2">"String"</span><span class="p">}]</span>
149+
<pre class="highlight"><code class="language-javascript"><span class="p">[</span><span class="s2">"Label1"</span><span class="p">,</span> <span class="s2">"Label2"</span><span class="p">]</span>
151150
</code></pre>
152151

153152
<h3 id="response-6">Response</h3>
@@ -183,10 +182,11 @@ <h2 id="replace-all-labels-for-an-issue">Replace all Labels for an Issue</h2>
183182
</code></pre>
184183

185184
<h3 id="input-3">Input</h3>
186-
187-
<pre class="highlight"><code class="language-javascript"><span class="p">[{</span><span class="s2">"name"</span><span class="o">=&gt;</span><span class="s2">"String"</span><span class="p">}]</span>
185+
<pre class="highlight"><code class="language-javascript"><span class="p">[</span><span class="s2">"Label1"</span><span class="p">,</span> <span class="s2">"Label2"</span><span class="p">]</span>
188186
</code></pre>
189187

188+
<p>Sending an empty array (<code>[]</code>) will remove all Labels from the Issue.</p>
189+
190190
<h3 id="response-8">Response</h3>
191191

192192
<pre class="headers"><code>Status: 200 OK

0 commit comments

Comments
 (0)