201, 202 HTTP Codes
154 views
Skip to first unread message
CPH
Nov 15, 2012, 4:15:38 PM11/15/12
to api-...@googlegroups.com
Are 201, 202 codes generally used with APIs or should I just always return 200 if there is not any sort of error?
Steve Klabnik
Nov 15, 2012, 4:25:47 PM11/15/12
to api-...@googlegroups.com
200 is never 'wrong,' but providing more detail is often good. I often
use 201 and 202.
use 201 and 202.
sune jakobsson
Nov 15, 2012, 4:58:24 PM11/15/12
to api-...@googlegroups.com
From the rfc2616 specification:
10.2 Successful 2xx
This class of status code indicates that the client's request was
successfully received, understood, and accepted.
10.2.1 200 OK
The request has succeeded. The information returned with the response
is dependent on the method used in the request, for example:
GET an entity corresponding to the requested resource is sent in the response;
HEAD the entity-header fields corresponding to the requested resource
are sent in the response without any message-body;
POST an entity describing or containing the result of the action;
TRACE an entity containing the request message as received by the end server.
10.2.2 201 Created
The request has been fulfilled and resulted in a new resource being
created. The newly created resource can be referenced by the URI(s)
returned in the entity of the response, with the most specific URI for
the resource given by a Location header field. The response SHOULD
include an entity containing a list of resource characteristics and
location(s) from which the user or user agent can choose the one most
appropriate. The entity format is specified by the media type given in
the Content-Type header field. The origin server MUST create the
resource before returning the 201 status code. If the action cannot be
carried out immediately, the server SHOULD respond with 202 (Accepted)
response instead.
A 201 response MAY contain an ETag response header field indicating
the current value of the entity tag for the requested variant just
created, see section 14.19.
10.2.3 202 Accepted
The request has been accepted for processing, but the processing has
not been completed. The request might or might not eventually be acted
upon, as it might be disallowed when processing actually takes place.
There is no facility for re-sending a status code from an asynchronous
operation such as this.
The 202 response is intentionally non-committal. Its purpose is to
allow a server to accept a request for some other process (perhaps a
batch-oriented process that is only run once per day) without
requiring that the user agent's connection to the server persist until
the process is completed. The entity returned with this response
SHOULD include an indication of the request's current status and
either a pointer to a status monitor or some estimate of when the user
can expect the request to be fulfilled.
10.2.4 203 Non-Authoritative Information
The returned metainformation in the entity-header is not the
definitive set as available from the origin server, but is gathered
from a local or a third-party copy. The set presented MAY be a subset
or superset of the original version. For example, including local
annotation information about the resource might result in a superset
of the metainformation known by the origin server. Use of this
response code is not required and is only appropriate when the
response would otherwise be 200 (OK).
10.2.5 204 No Content
The server has fulfilled the request but does not need to return an
entity-body, and might want to return updated metainformation. The
response MAY include new or updated metainformation in the form of
entity-headers, which if present SHOULD be associated with the
requested variant.
If the client is a user agent, it SHOULD NOT change its document view
from that which caused the request to be sent. This response is
primarily intended to allow input for actions to take place without
causing a change to the user agent's active document view, although
any new or updated metainformation SHOULD be applied to the document
currently in the user agent's active view.
The 204 response MUST NOT include a message-body, and thus is always
terminated by the first empty line after the header fields.
10.2.6 205 Reset Content
The server has fulfilled the request and the user agent SHOULD reset
the document view which caused the request to be sent. This response
is primarily intended to allow input for actions to take place via
user input, followed by a clearing of the form in which the input is
given so that the user can easily initiate another input action. The
response MUST NOT include an entity.
10.2.7 206 Partial Content
The server has fulfilled the partial GET request for the resource. The
request MUST have included a Range header field (section 14.35)
indicating the desired range, and MAY have included an If-Range header
field (section 14.27) to make the request conditional.
The response MUST include the following header fields:
- Either a Content-Range header field (section 14.16) indicating
the range included with this response, or a multipart/byteranges
Content-Type including Content-Range fields for each part. If a
Content-Length header field is present in the response, its
value MUST match the actual number of OCTETs transmitted in the
message-body.
- Date
- ETag and/or Content-Location, if the header would have been sent
in a 200 response to the same request
- Expires, Cache-Control, and/or Vary, if the field-value might
differ from that sent in any previous response for the same
variant
If the 206 response is the result of an If-Range request that used a
strong cache validator (see section 13.3.3), the response SHOULD NOT
include other entity-headers. If the response is the result of an
If-Range request that used a weak validator, the response MUST NOT
include other entity-headers; this prevents inconsistencies between
cached entity-bodies and updated headers. Otherwise, the response MUST
include all of the entity-headers that would have been returned with a
200 (OK) response to the same request.
A cache MUST NOT combine a 206 response with other previously cached
content if the ETag or Last-Modified headers do not match exactly, see
13.5.4.
A cache that does not support the Range and Content-Range headers MUST
NOT cache 206 (Partial) responses.
On 15 November 2012 22:25, Steve Klabnik <st...@steveklabnik.com> wrote:
> 200 is never 'wrong,' but providing more detail is often good. I often
> use 201 and 202.
>
> --
> You received this message because you are subscribed to the Google Groups "API Craft" group.
> To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/api-craft?hl=en.
>
>
10.2 Successful 2xx
This class of status code indicates that the client's request was
successfully received, understood, and accepted.
10.2.1 200 OK
The request has succeeded. The information returned with the response
is dependent on the method used in the request, for example:
GET an entity corresponding to the requested resource is sent in the response;
HEAD the entity-header fields corresponding to the requested resource
are sent in the response without any message-body;
POST an entity describing or containing the result of the action;
TRACE an entity containing the request message as received by the end server.
10.2.2 201 Created
The request has been fulfilled and resulted in a new resource being
created. The newly created resource can be referenced by the URI(s)
returned in the entity of the response, with the most specific URI for
the resource given by a Location header field. The response SHOULD
include an entity containing a list of resource characteristics and
location(s) from which the user or user agent can choose the one most
appropriate. The entity format is specified by the media type given in
the Content-Type header field. The origin server MUST create the
resource before returning the 201 status code. If the action cannot be
carried out immediately, the server SHOULD respond with 202 (Accepted)
response instead.
A 201 response MAY contain an ETag response header field indicating
the current value of the entity tag for the requested variant just
created, see section 14.19.
10.2.3 202 Accepted
The request has been accepted for processing, but the processing has
not been completed. The request might or might not eventually be acted
upon, as it might be disallowed when processing actually takes place.
There is no facility for re-sending a status code from an asynchronous
operation such as this.
The 202 response is intentionally non-committal. Its purpose is to
allow a server to accept a request for some other process (perhaps a
batch-oriented process that is only run once per day) without
requiring that the user agent's connection to the server persist until
the process is completed. The entity returned with this response
SHOULD include an indication of the request's current status and
either a pointer to a status monitor or some estimate of when the user
can expect the request to be fulfilled.
10.2.4 203 Non-Authoritative Information
The returned metainformation in the entity-header is not the
definitive set as available from the origin server, but is gathered
from a local or a third-party copy. The set presented MAY be a subset
or superset of the original version. For example, including local
annotation information about the resource might result in a superset
of the metainformation known by the origin server. Use of this
response code is not required and is only appropriate when the
response would otherwise be 200 (OK).
10.2.5 204 No Content
The server has fulfilled the request but does not need to return an
entity-body, and might want to return updated metainformation. The
response MAY include new or updated metainformation in the form of
entity-headers, which if present SHOULD be associated with the
requested variant.
If the client is a user agent, it SHOULD NOT change its document view
from that which caused the request to be sent. This response is
primarily intended to allow input for actions to take place without
causing a change to the user agent's active document view, although
any new or updated metainformation SHOULD be applied to the document
currently in the user agent's active view.
The 204 response MUST NOT include a message-body, and thus is always
terminated by the first empty line after the header fields.
10.2.6 205 Reset Content
The server has fulfilled the request and the user agent SHOULD reset
the document view which caused the request to be sent. This response
is primarily intended to allow input for actions to take place via
user input, followed by a clearing of the form in which the input is
given so that the user can easily initiate another input action. The
response MUST NOT include an entity.
10.2.7 206 Partial Content
The server has fulfilled the partial GET request for the resource. The
request MUST have included a Range header field (section 14.35)
indicating the desired range, and MAY have included an If-Range header
field (section 14.27) to make the request conditional.
The response MUST include the following header fields:
- Either a Content-Range header field (section 14.16) indicating
the range included with this response, or a multipart/byteranges
Content-Type including Content-Range fields for each part. If a
Content-Length header field is present in the response, its
value MUST match the actual number of OCTETs transmitted in the
message-body.
- Date
- ETag and/or Content-Location, if the header would have been sent
in a 200 response to the same request
- Expires, Cache-Control, and/or Vary, if the field-value might
differ from that sent in any previous response for the same
variant
If the 206 response is the result of an If-Range request that used a
strong cache validator (see section 13.3.3), the response SHOULD NOT
include other entity-headers. If the response is the result of an
If-Range request that used a weak validator, the response MUST NOT
include other entity-headers; this prevents inconsistencies between
cached entity-bodies and updated headers. Otherwise, the response MUST
include all of the entity-headers that would have been returned with a
200 (OK) response to the same request.
A cache MUST NOT combine a 206 response with other previously cached
content if the ETag or Last-Modified headers do not match exactly, see
13.5.4.
A cache that does not support the Range and Content-Range headers MUST
NOT cache 206 (Partial) responses.
On 15 November 2012 22:25, Steve Klabnik <st...@steveklabnik.com> wrote:
> 200 is never 'wrong,' but providing more detail is often good. I often
> use 201 and 202.
>
> You received this message because you are subscribed to the Google Groups "API Craft" group.
> To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/api-craft?hl=en.
>
>
Daniel Roop
Nov 16, 2012, 1:24:03 PM11/16/12
to api-...@googlegroups.com
I use many of the 2xx status codes in the apis I design. Including 201 and 202.
Romain Bessuges-Meusy
Dec 15, 2012, 8:46:32 AM12/15/12
to api-...@googlegroups.com
When returning a partial resource, is it recommended to use the 206 code ? In that case, how am I supposed to put the Range header ?
Reply all
Reply to author
Forward
0 new messages