HTTP Method Semantics
The web service interfaces that make up the Bali Nebula™ implement strict semantics to maintain consistency and security across all service access points. Not every resource type belonging to every service implements all HTTP method types. A service will respond with a status 405 (Method Not Allowed), if an attempt is made to call an unsupported method on a resource.
The following diagram shows the method semantics for accessing Bali documents across three dimensions:
- Whether or not the client has been authenticated.
- Whether or not the document already exists, and if so whether it is mutable.
- Whether or not the desired document allows access to the client.
Details of the resulting status codes and bodies for each method in each dimension are covered next.
This method attempts to create a new document that is subordinate and managed by the resource specified by the URI. If the resource does not exist, or if the subordinate document already exists, an error status is returned. Otherwise, the document is created using the contents of the request body.
- Status 201 - The document has been created and the response body contains a citation to the new document.
- Status 404 - The resource specified by the URI does not exist. The response body contains a description of the error.
- Status 409 - Both the resource and the subordinate document already exist. The response body contains a description of the error.
- Status 401 - The client making the request has not been authenticated and is not allowed to create new documents. The response body contains a description of the error.
This method attempts to create or update the document specified in the URI. If the document does not yet exist it is created, otherwise the document is updated using the contents of the request body. In either case, the response body contains a citation to the latest version of the document.
- Status 201 - The document has been created and the response body contains a citation to the new document.
- Status 200 - The existing document was updated and the response body contains a citation to the new version.
- Status 409 - The document already exists and is immutable. The response body contains a description of the error.
- Status 401 - The client making the request has not been authenticated and is not allowed to update documents. The response body contains a description of the error.
- Status 403 - The client making the request has been authenticated but is not allowed to update the document. The response body contains a description of the error. Note, this only leaks the existence of the document to an authenticated client.
This method attempts to delete the document specified in the URI. If the document does not exist, this method does nothing. Otherwise, the document is permanently deleted.
- Status 200 - The document was successfully deleted. The body of the response contains the last version of the deleted document.
- Status 404 - The document did not exist. The response body contains a description of the error.
- Status 401 - The client making the request has not been authenticated and is not allowed to delete documents. The response body contains a description of the error.
- Status 403 - The client making the request has been authenticated but is not allowed to delete the document. The response body contains a description of the error. Note, this only leaks the existence of the document to an authenticated client.
This method is used to check whether or not the document specified in the URI currently exists. The response body is always empty. The response status code may be mapped to a boolean value:
-
Status 200 - The document exists (maps to
true). document. -
Status 404 - The document does not currently exist (maps to
false). - Status 401 - The client making the request has not been authenticated and the document, if it exists, does not allow public access.
- Status 403 - The client making the request has been authenticated but is not allowed to access the document. Note, this only leaks the existence of the document to an authenticated client.
This method returns the document specified in the URI. If the document does not exist the body is empty. The resulting status code must be the same as if the same request was made using the HEAD method:
- Status 200 - The document exists and the client is allowed to access it. The response body contains the current version of the document.
- Status 404 - The document does not currently exist. The response body contains a description of the error.
- Status 401 - The client making the request has not been authenticated and the document, if it exists, does not allow public access. The response body contains a description of the error.
- Status 403 - The client making the request has been authenticated but is not allowed to access the document. The response body contains a description of the error. Note, this only leaks the existence of the document to an authenticated client.