Preamble

(Ce n'est qu'une ébauche. Comme c'est un projet qui est amené à prendre de l'empleur, j'ai commencé à rédiger en anglais. Tout est modifiable.)

RFC: REST API protocols definition for l'ouvre-boîte

Preamble

L'ouvre-boite is planning to leverage the resources of his team members to quickly prototype new and innovative Internet services. Each member, making use of his own resources, may propose an implementation of a service he think is useful to the community.

Programming languages being so diverse and programming habit being hard to change, it is easier at this point of time to let each member develop in his own language and offer the service as a web service. Decision has been made to use the REST architecture to allow interoperability.

To make is process as efficient as possible, it seems useful to have a common set of API between services.

• It is easier to use multiple services with a single syntax
• It is easier to mix and match data coming from different services
• A set of "best practices" can be built among the members.
• ...

Definitions

This RFC uses the following conventions:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119

Current resources

• http://www.ics.uci.edu/~rohit/ARRESTED-ICSE.pdf
• Mailing list
• http://rest.blueoxen.net/cgi-bin/wiki.pl
• http://www.xml.com/pub/a/2004/12/01/restful-web.html
• http://www.prescod.net/rest/mistakes/
• http://www.xfront.com/REST-Web-Services.html
• http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Referring to Atom REST Api could be a good thing given the current momentum around Atom, we could build on the current tools developed for it like the universal feed parser…

• http://www.intertwingly.net/wiki/pie/RestApiSupportSummary
• http://danja.typepad.com/fecho/
• http://www.intertwingly.net/wiki/pie/PutDeleteSupport
• Universal feed parser http://www.feedparser.org/

Existing services

del.icio.us

URL: http://del.icio.us

Api doc: http://del.icio.us/doc/api

Nouns:

• tag/(tagname)
• doc
• (username)
• rss/(username)
• rss/tag/(tagname)
• rss/tag/(username)/(tagname)
• popular

BlogMarks

URL: http://blogmarks.net/

Api doc: http://dev.blogmarks.net/cgi-bin/blogmarks.cgi/wiki/DeveloperDocs Nouns:

• tag/(tagname)
• user/(username)

6nergie

http://www.6nergies.net/

Based on Horde, Agora, PhpBb

No Api found yet.

Viabloga

http://www.viabloga.com

No Api found yet

RFC for REST at l'ouvre-boite

Definition of the basic verbs

• POST = create resource from XML entity
• PUT = rewrite resource from XML entity
• GET = get XML representation of resource
• DELETE = delete resource

Categorize your resources according to whether clients can just receive a representation of the resource, or whether clients can modify (add to) the resource. For the former, make those resources accessible using an HTTP GET. For the later, make those resources accessible using HTTP POST, PUT, and/or DELETE.

WSDL (Web Service Description Language) ?

URIs

• MainURL for the service is of the form http://www.mynicedomain.com/directory
• /rest main service URL
• /rest/methods machine readable documentation for supported methods
• /rest/error Human readable error message
• /rest/doc Human readable documentation

Nouns:

• /ver[0-9].[0-9]/ version of the service.

Status codes

• http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Data representation

Data is return as XHTML or XML based on content negotiation between the Web server and the User Agent. It may be useful to have an human readable (XHTML) representation of the data as an alternative to the machine parsable (XML) representation.

Base types

I suggest the use of the XML-RPC representations. This allow to leverage existing libraries for encoding and decoding simple transactions. Even Ruby has one : http://www.ruby-doc.org/stdlib/libdoc/xmlrpc/rdoc/

Complex types

• All text MUST be in UTF-8.
• Dates MUST be in ISO8601

MIME

gzip