1. General Rules

A new Content-type value is introduced for S2 layers, named application/x-danga-s2-layer. This is used both in server responses and client layer uploads.

1.1. Requests

When making a request to the S2 interface, you can authenticate with the remote server using HTTP Digest authentication[1] or some site-specific authentication method. On LiveJournal.com, session cookies are supported.

The request URL will vary between applications. On LiveJournal it can be found at /interface/s2.

An example uploading client named s2up.pl for the protocol, written in perl using LWP, is in the SVN repository[o].

The same URL is used for both retrieval and updating; the method used defines the action the server will take. On LiveJournal, that URL will be /interface/s2/layerid. How you find the correct layerid is outside the scope of this specification.

1.2. Responses

When parsing response bodies, consider only ASCII character 10 (newline, \n) to indicate a newline. Disregard any occurrences of ASCII 13 (carriage return, \r).

Error responses have a HTTP error code and a plain text response body. This will contain a short error message, then a newline, then a longer error message also followed by a newline, and optionally other data which you may wish to display.

If the response is not in the expected format (i.e. content-type does not indicate a plain text response) clients should simply explain that the server has returned an invalid response and that this may be temporary or might be due to an incorrect URL. Even in the case of an unparsable body, the HTTP response code can be used to infer the nature of the error.

You should be prepared to accept any HTTP response code and treat it as the HTTP spec advises. This includes the redirection codes. You are advised to use a full HTTP library, which is available for most languages, to make your requests rather than hacking up flakey HTTP code which assumes everything will always work in a particular way.

An exception to this rule is that the 403 Forbidden response is defined in HTTP to indicate that "authentication will not help". This protocol also allows for it to describe the condition where authentication credentials are given but the given account has no access to whatever was requested. This slight quirk is made under the assumption many clients for this protocol will be non-interactive and launched as tools from text editors, and prompting for alternative credentials would be impossible.

[1] Refer to RFC 2617[o] for more information.