Written By: Seairth Jacobs
Status: Draft
Version: 0.1
Date: August 28, 2003
Simple Interface Discovery (SID) is a simple, extensible way to discover one or more desired HTTP resource interfaces and their associated URIs. SID is an xml-based syntax which is easy to generate and process. By submitting a SID request to an appropriate web resource, that resource can tell you about interfaces of other resources related to it or additional information about its own interface(s). It can also be extended for more complex or proprietary URI discovery needs.
Any resource could perform SID processing. For instance, the "home page" resource may process SID requests to point to various site-wide resource/URIs. A blog entry may process SID request to point to locations for retrieving alternative versions or where to post comments. A resource could return information about itself concerning alternate content-types or content-encodings that can be returned with a GET. The possibilities are practically endless.
The basic format (without attributes) of a SID document looks like:
<sid>
<interface>
<accepts/>
<returns/>
</interface>
</sid>
The root element is the <sid> element. It contains one or more <interface> elements.
Each <interface> element represents the criteria for a single HTTP interface. In this case, an HTTP "interface" is defined as the possible request and response headers and entities associated to a single URI of a given resource. The <interface> element contains zero or more <accepts> or <returns> elements, as well as a uri attribute.
The <accepts> element represents either a series of capabilities that a client is asking a server to meet when accepting requests, or is a series of capabilities that the server claims it supports when accepting requests. The possible attributes for <accepts> are: content-type, content-encoding, http-method, and required.
The <returns> element represents either a series of capabilities that a client is asking a server to meet when returning a response, or is a series of capabilities that the server claims it supports when returning responses. The possible attributes for <returns> are: content-type, content-encoding, content-language, and required.
Both <accepts> and <returns> elements must have at least one attribute (not including the required attribute) to be considered significant and may have as many attributes as desired. All non-significant elements can be ignored. When viewing these attributes as a group, they are related by a logical AND, meaning that
<accepts content-type="text/xml" content-encoding="gzip"/>
would be read as "accepts requests with a content-type of "text/xml" and a content-encoding of "gzip".
The required attribute may have a value of "yes" or "no". If not given, the default value is "no". The purpose of this attribute depends on whether the document is being used in a request or a response. When used in a request, a value of "yes" indicates that the server MUST meet the associated capabilies for that <accepts> or <returns>, or else reject the request. When used in a response, a value of "yes" indicates that a client MUST know how to handle the associated capabilities for that <accepts> or <returns>. If a client cannot meet the required <accepts> or understand the required <returns>, it SHOULD NOT attempt to make a request to that interface. If the value of required is "no" (or absent), then the capabilities are desired and the client or server does not necessarily need to pay attention to them.
If the only objective of a SID request is to determine the capabilities of the interface associated to the request URI, then the SID document must not contain a value for the <interface>'s uri attribute and there must not be any significant <accepts> or <returns> elements. The simplest SID document for this purpose would be:
<sid><interface uri=""/></sid>
New attributes or elements may be added by way of extension. Extension in SID documents is done by way of XML Namespaces. To have meaning within the context of SID, extension elements and attributes SHOULD be placed inside of the <accepts> or <returns> elements. When processing extension elements, the required attribute value must still be honored, even if the extension namespace is not recognized.
When a client wants to discover a URI for a given interface, it creates a SID document and POSTs it to a resource that can authoritatively process SID documents. For each URI desired, the client includes an <interface> element with an empty uri attribute. Each <interface> element contains zero or more <accepts> or <returns> elements to define the desired (or required) interface capabilities of the URI being queried for. The resource examines each <interface> element and attempts to match the appropriate URI. If such a match can be made, it will set the uri attribute to that value. The server generates a response SID document matching the request document according to the following rules:
It is also possible for a client to "push" a URI to a server. In this case, a request <interface> element already contains a URI in the uri attribute. The <accepts> and <returns> elements indicate the features of the associated URI. The server receiving this request may examine the URI and use the criteria elements to determine if it should accept the URI (for whatever purposes) or not. If the server chooses to accept the URI, it leaves the URI the same in the response. If the server chooses not to accept the URI, it must make the uri attribute empty in the response. The criteria elements in the response MUST only be those that the server understood.
<sid>
<interface uri="">
<accepts content-type="image/png" http-method="POST" required="yes"/>
<returns content-type="image/jpg" required="yes"/>
<returns content-encoding="gzip"/>
</interface>
</sid>
This request indicates that the resource must accept POST requests with a content-type of "image/png". It must be able to return an "image/jpg". It may optionally return the response using "gzip" content-encoding.
<sid>
<interface uri="http://www.example.com/imageconverter">
<accepts content-type="image/png"/>
<accepts content-type="image/jpeg"/>
<accepts content-type="image/gif"/>
<accepts content-type="application/svg+xml"/>
<accepts content-encoding="gzip"/>
<accepts content-encoding="deflate"/>
<accepts http-method="POST"/>
<returns content-type="image/jpeg"/>
<returns content-type="image/png"/>
<returns content-encoding="gzip"/>
<returns content-type="application/svg+xml" content-encoding="gzip"/>
</interface>
</sid>
This response indicates that the requested interface is at the URI "http://www.example.com/imageconverter". The resource will accept POST requests with a content-type of "image/png", "image/jpeg", "image/gif", or "application/svg+xml", any of which can be encoded with "gzip" or "deflate". The resource can return either an "image/png", "image/jpeg" (either of which can be encoded with "gzip", or an "application/svg+xml" that MUST be encoded with "gzip".
In this example, the resource processing the SID request is a blog entry. The objective is to see if comments, trackbacks, etc. can be left.
<sid>
<interface uri="">
<accepts content-type="application/x.atom+xml"/>
<accepts content-type="application/x-www-form-urlencoded"
xmlns:f="http://example.com/FormFields">
<f:field f:name="title"/>
<f:field f:name="excerpt"/>
<f:field f:name="url"/>
<f:field f:name="blog_name"/>
</accepts>
<returns content-type="application/x.atom+xml"/>
</interface>
</sid>
This request indicates that the resource should accept requests with a content-type of "application/x.atom+xml" or "application/x-www-form-urlencoded". In the case of the second <accepts>, extension elements have been used to indicate which fields are expected (these are the field names used by MovableType's Trackback API). In this case, the client would like the response to have a content-type of "application/x.atom+xml".
<sid>
<interface uri="http://example.com/blog/SIDIsCool/comments">
<accepts content-type="application/x.atom+xml" http-method="POST"/>
<returns content-type="application/x.atom+xml" required="yes"/>
<returns content-encoding="gzip"/>
</interface>
</sid>
This response indicates that the requested interface is at the URI "http://example.com/blog/SIDIsCool/comments". The resource will accept POST requests with a content-type of "application/x.atom+xml" only. This means it does not accept Trackback pings. The resource also requires that the returned entity always have a content-type of "application/x.atom+xml" and that it may optionally be encoded with "gzip".