HTTP status conventions

Tizra POST operations follow use simplified HTTP-compatible status indication (extending the ones described for destination servers for the account status service).

Operation response codes

HTTP response codes should be used to signal errors, according to the standard.

• 201 "Created". This response indicates that a resource was successfully created. The administrative URL for the new resource is returned in the Location: header of the response. The Location URL can be used for other update and management operations.
• 200 Success. The information will be marked as transmitted at the Tizra end, and the operation will not be retried
• 3XX Redirects will not be accommodated for this interface, and will be treated as a fatal error and not retried.
• 400 bad syntax. The request cannot even be parsed properly, and retrying won't help. This can be used for any non-retryable error. In general, 400 errors should be used when retrying won't help.
• 406 bad semantics. The request is not valid, and retrying won't help.
• 401 Authentication required. Additional authentication over the SSL channel may be supported at some point, and this is the only 400 code on for which retry might make sense.
• 503 or 500 indicate an operation failure, and the content of the message-body will be the error message. 500 should be used for errors when retrying may work at a later time.

As with the account status service, 2xx responses indicate success, 3xx redirects (which may not be supported by all clients]), 4xx responses indicate some form of error that cannot be retried, while 5xx errors indicate server problems that may be resolved at a later time, or an unexpected error such as a bug.

This allows a client to tell if an error is due to a malformed request (which will never succeed against the current version of the server), a semantic problem with the request (perhaps a missing resource), which is unlikely to succeed as is, or if the error is due to a (potentially) transient problem at the server.

Success Results

The result of an HTTP request consists of an HTTP status (and perhaps headers), and a Response-body containing the content of the response. There are two success response codes:

• 200 OK (update performed)
• 201 Created (a new resource was created)

The Content-Body of API results from a server are JSON records indicating information about the result of the request. This information is included for any successful update, as the URLs for the actually updated document may be as unknown in advance as the URL for a newly created object is. Here's a simple example:

{
	"status":  201,
	"message": "created",
	"api-url" : "URL for Put, and future direct access to the state of the object",
	"webdav-url": "URL of the document for WebDAV update",
	"tizra-id": "The tizra id of the document, suitable for use with the query interface"
}

• status duplicates the HTTP status.
• message A human-readable description of the results. In the case of an error, this may contain a lot of information; normally very short.
• api-url A URL for POST, PUT, GET, etc. requests directed at the newly created object. This URL duplicates the Location: header, which is the HTTP default way to signal the location of a newly created resource.
• webdav-url The URL at which WebDAV operations can be performed as needed for file uploads (the "binary channel"). Currently described in Tizra WebDAV for developers. This URL will be for the document's location in the server, so for instance it will have folders under it call ~PdfSource, etc.
• tizra-id The Tizra database unique identifier for the created document.
• duplicates-deleted: If an update performed cleanup, the number of duplicate documents purged from the system is given here.

Error results

Error results always include the status and message fields, as well as an optional detail-status. The idea of detail status is that it can be used to provide more information about a specific error as a status code, rather than a full message with specifics of the particular error.