module Restfolia
Public: Restfolia: a REST client to consume and interact with Hypermedia API.
Against the grain, Restfolia
is very opinionated about some REST’s concepts:
-
Aims only *JSON Media Type*.
-
All responses are parsed and returned as
Restfolia::Resource
. -
Less is more.
Restfolia
is very proud to be small, easy to maintain and evolve. -
Restfolia::Resource
is Ruby object with attributes from JSON and can optionally contains *hypermedia links* which have to be a specific format. See the examples below. -
All code is very well documented, using “TomDoc”:tomdoc.org style.
Obs: This is a draft version. Not ready for production (yet!).
References
You can find more information about arquitecture REST below:
-
“Roy Fielding’s”:roy.gbiv.com/untangled see this post for example: “REST APIs must be hypertext-driven”:roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
-
“Rest in Practice”:restinpractice.com, especially the chapter titled “Hypermedia Formats”.
-
“Mike Amundsen’s Blog”:amundsen.com/blog/
-
ROAR - “Resource Oriented Arquitectures in Ruby”:github.com/apotonick/roar it seems really good to build a hypermedia API, of course you can go with Sinatra+rabl solutions too.
Examples
# GET http://localhost:9292/recursos/busca { "itens_por_pagina" : 10, "paginal_atual" : 1, "paginas_totais" : 1, "query" : "", "total_resultado" : 100, "resultado" : [ { "id" : 1, "name" : "Test1", "links" : [ { "href" : "http://localhost:9292/recursos/id/1", "rel" : "recurso", "type" : "application/json" } ] }, { "id" : 2, "name" : "Test2", "links" : [ { "href" : "http://localhost:9292/recursos/id/2", "rel" : "recurso", "type" : "application/json" } ] } ], "links" : { "href" : "http://localhost:9292/recursos/busca", "rel" : "self", "type" : "application/json" }, } # GET http://localhost:9292/recursos/id/1 { "id" : 1, "name" : "Test1", "links" : { "href" : "http://localhost:9292/recursos/id/1", "rel" : "self", "type" : "application/json" } } # getting a resource resource = Restfolia.at('http://localhost:9292/recursos/busca').get resource.pagina_atual # => 1 resource.resultado # => [#<Resource ...>, #<Resource ...>] # example of hypermedia navigation r1 = resource.resultado.first r1 = r1.links("recurso").get # => #<Resource ...> r1.name # => "Test1"
Constants
- VERSION
Public Class Methods
Public: Start point for getting the first Resource
.
url - String with the address of service to be accessed.
Examples
entry_point = Restfolia.at("http://localhost:9292/recursos/busca") entry_point.get # => #<Resource ...>
Returns Restfolia::EntryPoint
object.
# File lib/restfolia.rb, line 92 def self.at(url) EntryPoint.new(url) end
Public: Call a Factory of Resources. This is a good place to override and returns a custom Resource
Factory. By default, Restfolia
uses Restfolia::ResourceCreator
.
json - Hash parsed from Response body.
Returns Resource
instance, configured at ResourceCreator
. Raises ArgumentError if json is not a Hash.
# File lib/restfolia/resource_creator.rb, line 11 def self.create_resource(json) @creator ||= Restfolia::ResourceCreator.new @creator.create(json) end