ares_api_ideas

Ideias on a nicer ActiveResource API

= ActiveResource

== Guidelines

ARes is a platform to build clients to restful-like web services. It maps resources to objects that complies with the ActiveModel API.

To enjoy the advantages of being restful (whose discussion is beyond the scope of this gist), ARes should support:
  * using HTTP verbs, headers and status code as they are meant;
  * using hypermedia to drive application state and navigate between resources;
  * different and vendored media-types
  * the dinamic creation of resource types

When consuming Rails powered services, ARes defaults should match Rails defaults and ARes should work out of the box - basic crud, validations, associations. ARes should also be able to consume non-rails servers easily.

== Example client code

person = ActiveResource::Resource.at("http://example.com/people/1")
<< ActiveResource::Resource not loaded yet
# will be loadded by getting to uri when trying to access some attribute or link

person.name
person.parent # given parent is a link
<< ActiveResource::Resource, not loaded yet

person.parent.name
<< automatically gets parent href
person.parent.as("application/vnd.parent+xml")

person.parent.update_attribute(:name, "Paul")
# issues PATCH (or PUT) request to parent uri

person.brothers << {name: "Malena"}
person.save
# issues POST to brothers url

ActiveResource::Resource.at("http://example.com/people/1").as(:xml) # uses built-in xml formatter
ActiveResource::Resource.at("http://example.com/people/1".as("application/vnd.sun.Status+json") # uses built-in json formatter
ActiveResource::Resource.at("http://example.com/people/1").as(MyMediaTypeFormatter)
ActiveResource.at("http://example.com/people/1").get / post / put / delete
ActiveResource.at("http://example.com/people/1").update_attribute / save / destroy
ActiveResource.at("http://example.com/people").first / all / last / new / create
ActiveResource.at("http://example.com").at("/people")

class Person < ActiveResource::Base
  at "http://example.com"
  as :xml
end

class Person < ActiveResource::Base
  site "http://example.com"
  media_type :xml
end

Person.all ...

2. Ah HTTP Link headers, I can dig that. Riak does the same thing. It's funny when curl blows up because Riak Buckets have a massive Link header pointing to several thousand documents :)

3. I wasn't sure if that was in the person body or not. Sounds good.

4. Sure, but #as also takes strings and symbols in the examples. I'm just suggesting Mime classes could be another option. I prefer that to hardcoding "application/vnd.sun.Status+json".

5. OpenSearch is focused on paginate links, not necessarily the URL templating. Something like http://example.com?q={searchTerms}&c={example:color?} isn't clear on how to handle the case where the color option isn't given. Is there just an empty ?c param? URI Templates handle that. The syntax is nasty, but it works well. Addressable has a parser.

Though I think you're right that Rails can specify that the value is a string, and leave the rest up to the API lib.

6. Sounds good. I'll help out where I can. Though I can't guarantee GitHub will ever work on ARes. I'm toying with the idea of sending back pagination info in collections (very similar to OpenSearch, only in JSON). Also, I hate how Rails adds the nested hash to every item. I understand why it's there (I campaigned for its addition and wrote that code...), but I want our API to be as awesome as possible. I wonder if custom mimetypes can solve this issue though?

class User < ARes::Base
  # maybe this is set by convention by singular/plural class name when you add
  # vendor :github
  #
  as "application/vnd.github.user+json"
  collected_as "application/vnd.github.users+json"
end

GET /users
HTTP/1.1 200 OK
Content-Type: application/vnd.github.users+json, charset=utf-8

{
  # my own custom opensearch-style properties
  "offset": 0,
  "total": 813,
  "per_page": 30,
  "users": [
    {"id": 1, "login": "technoweenie", "uri": "/users/1"}
  ]
}

GET /users/1
HTTP/1.1 200 OK
Content-Type: application/vnd.github.user+json, charset=utf-8

{"id": 1, "login": "technoweenie", "uri": "/users/1"}

Still thinking about link headers... I could just encode pagination info there.

Link: </users?limit=30&after=232232> railstag="next"; </users?limit=30&after232202> railstag="prev"

This is very loosely based on Riak link headers.

About 1 to 5: agreed! URI templates sounds interesting. Definitely worth the investigation.

However, I didn't understand what you mean with: "Also, I hate how Rails adds the nested hash to every item." But yes, the issue could probably be solved by custom formatters/mime types.

Sorry, I'm only talking about JSON. It wraps every object in a hash so that you can access it like xml/form responses with something like params[:ticket].

$ curl http://rails.lighthouseapp.com/projects/8994/tickets.json | json_reformat
  "tickets": [
    {
      "ticket": { ... },
      "ticket": { ... }
    }

:emo: this is indeed ugly. Maybe we could move this concern to the formatter and it would receive an array of hashes but would properly parse it and create params[:ticket] based on the root name.

Yes, based on a custom mime type. That rocks :) So much cleaner than param_parsers. That's exactly what I was thinking with that collected_as example above.