[XML-SIG] REST made more concrete still

[akuchlin@mems-exchange.org]

On Tue, Feb 19, 2002 at 10:38:39PM -0500, akuchlin@mems-exchange.org wrote:
>I have a project currently specified as a set of XML-RPC interfaces;
>RESTifying it will make an interesting thought experiment.

Notes on a vague REST interface are now at
http://www.amk.ca/conceit/rest-version.html.  The text follows.  Any
thoughts?
   
                      REST-ifying the Matisse Interfaces
     _________________________________________________________________
   
Introduction

   I wrote up a set of still-unimplemented XML-RPC interfaces for a
   project; see [4]the original spec for the full details. This page is
   an attempt at creating a strawman REST version of the spec, in an
   effort to figure out how REST should be applied. It will go through
   each of the interfaces, and compare the XML-RPC and REST version.
   
   In the XML-RPC version, users and services are identified by IDs such
   as "akuchlin" or "snf-scope". In the REST version, they're identified
   by URIs. The root URL for the REST version is called written here as
   master; it would eventually be a real URL such as
   http://services.mems-exchange.org.
   
Interface: Directory

\begin{methoddesc}{list_services}{\optional{application}}
Returns all the existing services as a list of structs.  The contents
of the structs are explained below.  \var{application} is a string
containing an application ID; if it's provided, then only services for
that application will be returned.
\end{methoddesc}

   REST version:
   GET master/list_services
   Returns a list of services as the body.
   XXX should the optional 'application argument be a URL parameter? Then
   you'd do "GET master/list_services;scope" to get all the microscope
   services. Or should it be the query string?
   XXX how should the returned result, which are (service ID, application
   ID, host, port) 3-tuples, be encoded? As an XML-RPC array of structs?
   As a little custom XML schema?

\begin{methoddesc}{get_service}{service}
Returns a struct (= a Python dictionary or a Java \class{Vector}
instance) with information about the given service.  The contents of
the struct are explained below.  \var{service} is a string containing
a service ID.
\end{methoddesc}

   REST version: GET master/service;service ID. Returns an HTTP body,
   encoded using the same schema/form as list_services().
   
Interface: Login

\begin{methoddesc}{get_service_ticket}{user_id, password, service_id}
If the user ID and password are correct, returns a string containing a
ticket for the given service.  If they're wrong, it will raise a fault
with the fault code 1 and fault string ``IncorrectPassword''.
\var{user_id}, \var{password}, \var{service_id} are all strings.
\end{methoddesc}

   REST version: POST master/get_service_ticket. This must be HTTP
   authenticated with the username (meaning a human-friendly ID as
   opposed to a URI?) and password. The body is the service ID. Returns
   an authorization ticket as the body.
   XXX should the service ID be specified as a query string?
   XXX or should this be a subset of the service's URI, so you'd access
   master/(service ID)/get_ticket, instead?
   
Interface: Authorization

\begin{methoddesc}{check}{user_id, service_id}
Returns a Boolean value.  Returns true if the user \var{user_id}
is permitted to access the service identified by \var{service_id}.
\end{methoddesc}

   REST version: POST master/check_auth
   XXX how should the two parameters be passed? (XML-RPC again?)
   
Interface: MetadataStore

\begin{methoddesc}{get_cache_location}{ticket, metadata}
\var{ticket} and \var{metadata} are both strings.  Returns a string
containing an FTP URL; the data should be stored to this URL.

(Rationale for choosing FTP: it's standard, it seems hard to improve
on it for shipping data at high speed, and the DPSS code supports it.)
\end{methoddesc}

   REST version: POST master/get_cache_location. The body is your
   authorization ticket. The returned body is the new URI for the data
   time. HTTP PUT the content to the URI to store the data; HTTP PUT the
   metadata to URI/metadata to store it.
   XXX what if you crash after getting the new URI? You now have an empty
   resource. Can this all be done in one HTTP operation?
   
Interface: MetadataSearch

\begin{methoddesc}{search}{ticket, condition1, condition2, ...}
Returns a list of metadata IDs that match all of the given conditions.

... full description deleted ...
\end{methoddesc}

   REST version: No equivalent is attempted. You could let Google crawl
   the URIs for your data, build RDF or topic maps or whatever you like.
   This interface goes away and is replaced by the panoply of search
   technologies available for the Web.
   
Interface: Preferences

\begin{methoddesc}{get_preferences}{ticket, service/application}
Retrieve a string containing preferences information.
\end{methoddesc}
\begin{methoddesc}{set_preferences}{ticket, service/application, prefdata}
Store the string \var{prefdata} containing preferences information.
\end{methoddesc}

   REST version: easy! To get preferences, POST
   user-URI/prefs/applicationID, passing an authorization ticket as the
   body. To set preferences, PUT to the same URI, passing the preference
   data in the body.

References

   4. http://www.mems-exchange.org/projects/matisse/ideas/
   5. http://www.mems-exchange.org/feedback/?akuchlin,www.amk.ca/conceit/rest-version.html

--amk                                                  (www.amk.ca)
I say, what a wonderful butler; he's so violent!
    -- The Doctor, in "City of Death"