HTTP facilities supported

From Alistair Mann / csi18n
Jump to: navigation, search

Except where noted, the use of the following is in accordance with RFC-2616

Methods

Method Notes
DELETE Deleted resources are flagged deleted, not actually deleted.
GET
HEAD
OPTIONS
POST Representations above 16,384 bytes may be declined.
PUT Representations above 16,384 bytes may be declined
Put can also be arranged via overloading the POST method for those libraries not offering PUT.

Overloading POST to implement PUT

Many browsers suffer from not implementing the HTTP PUT method. In order to implement it, send a POST instead and include the following html:

<input type="hidden" name="tinyurl.com/methodsunderstanding" value="put">

On receipt, the service will behave as if PUT was used.

HTTP Persistence and HTTP Pipelining

HTTP Persistence allows clients to send new requests over an existing open connection. If no new request is received within 10 seconds of the previous response, the connection will be closed by the server. More info at Wikipedia

HTTP Pipelining allows multiple requests to be made one after the other - indeed, in the same TCP packet - to the server, and to see them honoured with consecutive responses made per the order received. Pipelining would be useful if you know in advance that you'll need to GET two or more newmarks: each GET request can be issued as soon as ready or all-at-once without waiting for the previous GETs to complete. More info at Wikipedia

These facilities are provided through the Apache HTTPd server, rather than through csi18n.

Request headers to service

The following headers

Header Notes
Accept
Accept-Charset If used, must be UTF-8 or * otherwise will cause a 406 Not Acceptable
Accept-Encoding If used, must be identity or * otherwise will cause a 406 Not Acceptable
Accept-Language
Authorization Basic Access only.
csi18n is currently only available over SSL.
Security discussed here
Connection
Content-Encoding If used, must be identity or * otherwise will cause a 415 Unsupported media type
Content-Disposition
Content-Language If detected, will cause 501 Not Implemented
Content-Length
Content-MD5
Content-Range If detected, will cause 416 Requested range not satisfiable
Content-Type
Expect If this reaches the csi18n service, it must be 100 Continue which is ignored, otherwise it will cause 417 Expectation failed
If-Match
If-None-Match This header is ignored should the If-Match header also be supplied
If-Modified-Since More reliable results using X-CDMI-If-Modified-Since instead
If-Unmodified-Since More reliable results using X-CDMI-If-Unmodified-Since instead.

This header is ignored should the If-Modified-Since header also be supplied

Transfer-Encoding If used it must be chunked which is ignored, otherwise it will cause 501 Not Implemented
TE If used it must be chunked which is ignored, otherwise it will cause 501 Not Implemented
X-APIKEY
X-CDMI-If-Modified-Since
X-CDMI-If-Unmodified-Since This header is ignored should the X-CDMI-If-Modified-Since header also be supplied
X-Track-Security Used to have the server log progress as it moves the security subsystem. The log is not available to remote users

Reply headers from service

Header Notes
Allow
Cache-Control
Content-Language
Content-Length
Content-Location
Content-MD5
Content-Type
Date Prefer to use X-CDMI-Date
ETag
Expires
Last-Modified Prefer to use X-CDMI-Last-Modified
Location
Retry-After
Vary
WWW-Authenticate Security discussed here
X-CDMI-Date
X-CDMI-Last-Modified
X-Quote-Of-The-Session
X-Server
X-Testing-Dupe Repeats the HTTP Status Line
X-Warning-{N} Where {N} is an ascending number.

Representation formats

Format Notes
HTML text/html
JSON application/json
PHP text/vnd.php.serialized
plain text/plain
plain prs.mpsvr.getable
XML application/xml

HTTP Status Codes implemented

The csi18n service is made available through Apache HTTPd server. The following is a list of status code that the csi18n service itself may use. Codes not listed here will not be emitted by the csi18n service, but may be emitted upstream.

Code RFC meaning Notes
200 OK
201 Created
202 Accepted
204 No Content
205 Reset Content
301 Moved Permanently
303 See Other Issued when RBAC security has a note to send the client to another URI.

For more info, see RBAC Access

304 Not Modified
400 Bad Request
401 Unauthorised The body will normally describe why authorisation failed. Security discussed here
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
415 Unsupported Media Type
416 Requested Range Not Satisfiable
417 Expectation Failed
420 Enhance your calm
451 Unavailable For Legal Reasons
500 Internal Server Error
501 Not Implemented
503 Service Unavailable
521 Todo. Code has somewhere to live, but hasn't yet been written
522 Test. Placeholder used for unit tests and other purposes