Module: Restfolia
- Defined in:
- lib/restfolia.rb,
lib/restfolia/http.rb,
lib/restfolia/version.rb,
lib/restfolia/resource.rb,
lib/restfolia/exceptions.rb,
lib/restfolia/entry_point.rb,
lib/restfolia/resource_creator.rb
Overview
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"
Defined Under Namespace
Modules: HTTP Classes: EntryPoint, Resource, ResourceCreator, ResponseError
Constant Summary collapse
- VERSION =
"1.0.0"
Class Method Summary collapse
-
.at(url) ⇒ Object
Public: Start point for getting the first Resource.
-
.create_resource(json) ⇒ Object
Public: Call a Factory of Resources.
Class Method Details
.at(url) ⇒ Object
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.
93 94 95 |
# File 'lib/restfolia.rb', line 93 def self.at(url) EntryPoint.new(url) end |
.create_resource(json) ⇒ Object
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.
11 12 13 14 |
# File 'lib/restfolia/resource_creator.rb', line 11 def self.create_resource(json) @creator ||= Restfolia::ResourceCreator.new @creator.create(json) end |