I am in the process of writing a Services 3.0 Module based RESTful API for a WebApp I am developing.
I have prior experience creating an XMLRPC API through Services, and Services itself handles all the nitty-gritty of coding up a RESTful interface... While googling to find information, I located lots of "hello world" style RESTful examples in oodles of different languages, and I found upteen definitions of REST and descriptions about that PHD dude that wrote it up formally... but I'm not finding anyplace where developers have discussed or are discussing RESTful architectures of anything other than a simple, single level data service.
I have two resource types that I want to expose with my API, but they are not simple direct mappings to a CRUD pattern, so I am seeking a sounding board to hash out this design...
The first resource is a hierarchical object, simply called a "project". However, a project is able to create an unlimited number of 5 different types of additional sub-objects. And a project is able to direct the 2nd resource I want to expose as an API, and 'compile' the sub-objects within to create a new object of a 6th data type. So, in total, a 'project' is a hierarchical object that manages 7 different Drupal Content Types. Project included, each Content Type has a 'traditional' Drupal title, body, and comments, as well as additional custom fields and taxonomy.
Now, if a "project" were flat, non-hierarchical, then the REST example given at http://drupal.org/node/783460 would be fine. However, due to the hierarchical nature of a project, I'm not sure if I should be creating a single end-point for the entire project and all its sub-objects, or if the project gets one end-point and each of the 6 sub-objects gets their own end-point, with some project identifier included in their parameters (I'm still coming up to speed on the RESTful terminology.)
The 2nd resource I want to expose is a RESTful interface to control a physical machine. I am fairly confused as to how I'd map a CRUD pattern to a physical machine. This machine is controlled by the WebApp, and we want to expose a RESTful API for third parties to at least query to see if it is up, as well as install and update their 'use license' of the machine. Perhaps the machine does not get an interface at all, but gets a 'license' resource, because that could map to a CRUD pattern...
Anyone know of any online discussion group talking about such issues? How's about a RESTful design book?
All I'm finding myself are attempts to convince me that REST is good (I'm convinced), and "hello world" examples in different languages (Services takes care of the specific implementation details, so those discussions are irrelevant). Where to find help in designing a complex RESTful API?
Comments
Found a good resource
The book "RESTful Web Services" by Richardson & Ruby, published by O'Reilly starts out just like all the web sites out there, convincing you that REST is great and giving code examples in several languages. But after several chapters, it gets into the design aspects, and even discusses creating RESTful interfaces to physical machines.
I use 'RESTful Web Services'
I use 'RESTful Web Services' on most jobs. There's also some useful material at http://code.google.com/p/implementing-rest/ Also see http://www.infoq.com/articles/webber-rest-workflow
Interest in RESTful Service API development
I'm in the process of designing a RESTful API in Java for enterprise use (although as time goes on it might take on another un-enterprise flavor). The book you spoke of by Richardson and Ruby is outstanding. I am very interested in seeing if/how Drupal could fit into the API I'm working on. Drupal is already in our organization and support for it is growing. With the limited research I've done it seems the Drupal Services module can be used to expose Drupal resources "RESTfully" to other clients but I also would like to look into 1) having Drupal consume RESTful services and represent the resources exposed by the services, 2) have Drupal invoke PUT, DELETE, and POST methods on resources living outside it's own data store. There are scenarios where I would like to easily create a web form within Drupal but have the submission posted to an external resource via an external API. Current project load hasn't allowed me to dig too deeply into this but I saw this post and it immediately caught my eye.
Paulmorris: I've completed
Paulmorris: I've completed the 1.0 version of my RESTful API using Services 3, and from that experience I can tell you:
1) having Drupal consume RESTful services and represent the resources exposed by those services is not difficult at all,
2) having Drupal invoke PUT, DELETE, and POST methods on resources living outside it's own data store is also quite easy (does not require Services module for that)
(Aren't both those items you list sorta the same thing?) It is very straight forward to programmatically generate any web form you like, and submit that to external resources. However, I should point out that for what you're talking about, you pretty much don't need the Services module, unless you want your Drupal installation to expose its own API. (Maybe you're thinking of your Drupal exposed API being a 'dispatcher' of sorts to multiple other remote APIs? Yes, totally doable.)
Having got my RESTful API communicating with local java script, remote Drupal sites, remote non-Drupal sites, and remotely executed BASH shell scripts using cURL, I'm turning my attention to java now. I really love the language & device & environment freedom possible with RESTful services.
You may find this post of mine useful: http://drupal.org/node/1070066