dm-rest-adapter¶ ↑

A DataMapper adapter for REST Web Services

Usage¶ ↑

DM Rest Adapter requires the use of a model which is the same name as the resource you are using. For example, if you have a resource named “posts” you will create a standard datamapper object called post.rb in app/models. The only difference in this model is you will need to define the rest adapter for the model.

The following is an example of a post model, where the host settings point to the app you are running the resource on. In addition I have included a basic auth login which will be used if your resource requires auth:

DataMapper.setup(:default, {
  :adapter  => 'rest',
  :format   => 'xml',
  :host     => 'localhost',
  :port     => 4000,
  :login    => 'user',
  :password => 'verys3crit'
})

class Post

  include DataMapper::Resource

  property :id, Serial
  property :title, String
  property :body,  Text

end

If you notice this looks exactly like a normal datmapper model. Every property you define will map itself with the xml returned or posted from/to the resource.

Code¶ ↑

Now for some code examples. DM Rest Adapter uses the same methods as datamapper including during creation.

Post.first
# => returns the object from the resouce
Post.get(1)
# => returns the object from the resource
p = Post.new(:title => "My awesome blog post", :body => "I really have nothing to say...")
p.save
# => saves the resource on the remote

Path extensions (.xml, .json, etc)¶ ↑

By default, dm-rest-adapter does not append an extension to each URI when performing requests. The HTTP specification defines two headers which should be used to indicate the type of content being sent by a client, and the types of content the client may accept in response; Content-Type and Accept.

Since some clients couldn’t set these headers, some frameworks adopted a workaround which was to permit specifying the content type as part of the URL, for example “/books.xml”, or “/books.json”.

However, since setting headers is no problem for us, we don’t do it, and instead trust the upstream provider to correctly handle the Content-Type and Accept headers (most web frameworks do this just fine). If you find that your REST endpoint requires such an extension to be present, you should:

1. Politely request that the service provider fixes their application so as to use the Accept and Content-Type headers.

2. In the mean-time, configure your repository with an :extension => true option:

   DataMapper.setup(:default, {
     :adapter  => 'rest',
     :format   => 'xml',
     # [...]
     :extension => true
   })
   

   This will tell the adapter to append the file extension.

Caveat¶ ↑

Posts do not honor RESTful HTTP status codes. I might fix this…

TODO:¶ ↑

Nested resources Put verb actions