173 lines
8.0 KiB
XML
Executable File
173 lines
8.0 KiB
XML
Executable File
<title>S2 Client Protocol</title>
|
|
<para>
|
|
This protocol, initially implemented for
|
|
<ulink url="http://www.livejournal.com/">LiveJournal</ulink> but applicable
|
|
elsewhere, provides a machine-friendly interface to an S2 system on a
|
|
remote server.
|
|
</para>
|
|
<para>
|
|
The protocol is just HTTP, so you can implement it using any suitable HTTP
|
|
library, including the Perl LWP library.
|
|
</para>
|
|
<section id="&s2.idroot;csp.general">
|
|
<title>General Rules</title>
|
|
<para>
|
|
A new <parameter>Content-type</parameter> value is introduced for S2 layers, named
|
|
<literal>application/x-danga-s2-layer</literal>. This is used both in server
|
|
responses and client layer uploads.
|
|
</para>
|
|
<section id="&s2.idroot;csp.general.request">
|
|
<title>Requests</title>
|
|
<para>
|
|
When making a request to the S2 interface, you can authenticate with the
|
|
remote server using either HTTP Digest authentication<footnote id="&s2.idroot;csp.general.ftn.digest_auth">
|
|
<simpara>
|
|
Refer to <ulink url="http://www.faqs.org/rfcs/rfc2617.html">RFC 2617</ulink>
|
|
for more information.
|
|
</simpara>
|
|
</footnote>
|
|
or some site-specific authentication method. On LiveJournal, session
|
|
cookies are supported.
|
|
</para><para>
|
|
The request URL will vary between applications. On LiveJournal it can be
|
|
found at <systemitem class="systemname">/interface/s2</systemitem>.
|
|
</para><para>
|
|
The same URL is used for both retrieval and updating; the method used
|
|
defines the action the server will take. On LiveJournal, that URL wil be
|
|
<systemitem class="systemname">/interface/s2/<replaceable>layerid</replaceable></systemitem>.
|
|
How you find the correct layerid is outside the scope of this specification.
|
|
</para>
|
|
</section>
|
|
<section id="&s2.idroot;csp.general.response">
|
|
<title>Responses</title>
|
|
<para>
|
|
When parsing response bodies, consider only ASCII character 10 (newline, \n)
|
|
to indicate a newline. Disregard any occurances of ASCII 13 (carriage return, \r).
|
|
</para><para>
|
|
Error responses will have an HTTP error code and have 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.
|
|
</para><para>
|
|
If the response is not in the expected format (ie, content-type does not
|
|
indicate a plain text response) clients should simply explain that the
|
|
server has returned an invalid response and that this might be temporary
|
|
or 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.
|
|
</para><para>
|
|
You should be prepared to accept any HTTP response code and treat it as
|
|
the HTTP spec describes. 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.
|
|
</para><para>
|
|
An exception to this rule is that the <returnvalue>403 Forbidden</returnvalue>
|
|
response is defined in HTTP to indicate that "authentication will not help",
|
|
but 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
|
|
being retrieved. This slight quirk is made under the assumption that many
|
|
clients for this protocol will be non-interactive and launched as tools
|
|
from text editors, and prompting for alternative credentials would be
|
|
impossible.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section id="&s2.idroot;csp.download">
|
|
<title>Retrieve Layer Source</title>
|
|
<para>
|
|
In order to get the S2 source of a layer for local editing, a simple GET
|
|
request is sufficient:
|
|
</para>
|
|
|
|
<programlisting>GET /interface/s2/1 HTTP/1.0
|
|
Host: www.livejournal.com
|
|
Accept: application/x-danga-s2-layer</programlisting>
|
|
|
|
<para>
|
|
In addition to the basic headers shown above, some form of authentication
|
|
can be used. See the HTTP specification for documentation on Basic
|
|
authentication. Anonymous requests are allowed, but the server may respond
|
|
with <returnvalue>401 Unauthorized</returnvalue>, describing the standard HTTP
|
|
authentication methods supported. Some servers, as described above, may
|
|
implement "special" authentication methods, such as LiveJournal supporting
|
|
website session cookies. These are not described (in a machine-readable way,
|
|
at least) in the Unauthorized response.
|
|
</para>
|
|
<para>
|
|
Client authors are <emphasis>strongly advised</emphasis> to send the
|
|
<parameter>Accept</parameter> header, as in the future other formats
|
|
may be supported and the server will be able to see which
|
|
format you are expecting and either honour your request or return the
|
|
response <returnvalue>Unnacceptable</returnvalue> if S2 layer source
|
|
as we know it now is unavailable.
|
|
</para>
|
|
<para>
|
|
If the response is an error, the response body will contain a short error
|
|
and then a longer error separated by a newline character, plus optionally
|
|
further error lines which you may wish to display if they are present. The
|
|
HTTP response code will give you some idea of the nature of the error.
|
|
</para>
|
|
<para>
|
|
If the response is successful (response code is 200 OK), and the
|
|
<parameter>content-type</parameter> is <literal>application/x-danga-s2-layer</literal>,
|
|
you will find S2 source in the response body. As with error responses,
|
|
you should consider only ASCII 10 (\n) to mean newline. Disregard ASCII 13
|
|
(\r). You may transform the returned \n characters to the local newline
|
|
representation for output if you wish.
|
|
</para>
|
|
</section>
|
|
<section id="&s2.idroot;csp.upload">
|
|
<title>Upload a Layer</title>
|
|
<para>
|
|
This mechanism can only be used to update an existing layer. This version
|
|
of the protocol does not allow for new layers to be created via the
|
|
interface. The S2 application will provide some mechanism, probably
|
|
human-oriented, to do this.
|
|
</para>
|
|
<para>
|
|
Uploading is done via an HTTP PUT request. The URL is the same used to
|
|
retrieve the given layer.
|
|
</para>
|
|
|
|
<programlisting>PUT /interface/s2/1 HTTP/1.0
|
|
Host: www.livejournal.com
|
|
Content-Length: 65
|
|
Content-Type: application/x-danga-s2-layer
|
|
|
|
layerinfo "type" = "layout";
|
|
layerinfo "name" = "Upload Example";
|
|
...
|
|
</programlisting>
|
|
|
|
<para>
|
|
If the given layer is an acceptable replacement for the layer indicated,
|
|
the server will respond with either <returnvalue>201 Created</returnvalue>,
|
|
which means that the layer is accepted and has been updated on the system,
|
|
or <returnvalue>202 Accepted</returnvalue>, indicating that the layer was
|
|
acceptable but the system will not instantly replace the existing layer
|
|
with it for reasons unspecified.
|
|
</para>
|
|
<para>
|
|
The server can also respond with any HTTP error code. The code
|
|
<returnvalue>500</returnvalue> is used to indicate that the server is unable
|
|
to accept the layer. If this is due to a layer compile error, the error will
|
|
be given in the optional part of the error response after the short and long
|
|
error descriptions.
|
|
</para>
|
|
<note>
|
|
<title>Optional Client Features</title>
|
|
<simpara>
|
|
A client with access to a local S2 compiler may wish to perform a
|
|
syntax check on the layer to be uploaded to avoid a round-trip to
|
|
the server for a syntax problem which could be resolved locally.
|
|
However, an option to override this should be provided to allow
|
|
for future changes to S2 syntax which may cause parse errors in
|
|
older versions of the compiler.
|
|
</simpara><simpara>
|
|
It is not advisable for the local client to attempt the checker
|
|
phase of compilation, as this is slow and local copies of parent
|
|
layers will frequently become out of date with that on the server.
|
|
</simpara>
|
|
</note>
|
|
</section>
|