239 lines
6.5 KiB
Plaintext
239 lines
6.5 KiB
Plaintext
= Action Web Service -- Serving APIs on rails
|
|
|
|
Action Web Service provides a way to publish interoperable web service APIs with
|
|
Rails without spending a lot of time delving into protocol details.
|
|
|
|
|
|
== Features
|
|
|
|
* SOAP RPC protocol support
|
|
* Dynamic WSDL generation for APIs
|
|
* XML-RPC protocol support
|
|
* Clients that use the same API definitions as the server for
|
|
easy interoperability with other Action Web Service based applications
|
|
* Type signature hints to improve interoperability with static languages
|
|
* Active Record model class support in signatures
|
|
|
|
|
|
== Defining your APIs
|
|
|
|
You specify the methods you want to make available as API methods in an
|
|
ActionWebService::API::Base derivative, and then specify this API
|
|
definition class wherever you want to use that API.
|
|
|
|
The implementation of the methods is done seperately to the API
|
|
specification.
|
|
|
|
|
|
==== Method name inflection
|
|
|
|
Action Web Service will camelcase the method names according to Rails Inflector
|
|
rules for the API visible to public callers. What this means, for example
|
|
is that the method names in generated WSDL will be camelcased, and callers will
|
|
have to supply the camelcased name in their requests for the request to
|
|
succeed.
|
|
|
|
If you do not desire this behaviour, you can turn it off with the
|
|
ActionWebService::API::Base +inflect_names+ option.
|
|
|
|
|
|
==== Inflection examples
|
|
|
|
:add => Add
|
|
:find_all => FindAll
|
|
|
|
|
|
==== Disabling inflection
|
|
|
|
class PersonAPI < ActionWebService::API::Base
|
|
inflect_names false
|
|
end
|
|
|
|
|
|
==== API definition example
|
|
|
|
class PersonAPI < ActionWebService::API::Base
|
|
api_method :add, :expects => [:string, :string, :bool], :returns => [:int]
|
|
api_method :remove, :expects => [:int], :returns => [:bool]
|
|
end
|
|
|
|
==== API usage example
|
|
|
|
class PersonController < ActionController::Base
|
|
web_service_api PersonAPI
|
|
|
|
def add
|
|
end
|
|
|
|
def remove
|
|
end
|
|
end
|
|
|
|
|
|
== Publishing your APIs
|
|
|
|
Action Web Service uses Action Pack to process protocol requests. There are two
|
|
modes of dispatching protocol requests, _Direct_, and _Delegated_.
|
|
|
|
|
|
=== Direct dispatching
|
|
|
|
This is the default mode. In this mode, controller actions implement the API
|
|
methods, and parameters for incoming method calls will be placed in
|
|
<tt>@params</tt> (keyed by name), and <tt>@method_params</tt> (ordered list).
|
|
|
|
The return value of the action is sent back as the return value to the
|
|
caller.
|
|
|
|
In this mode, a special <tt>api</tt> action is generated in the target
|
|
controller to unwrap the protocol request, forward it on to the relevant action
|
|
and send back the wrapped return value. <em>This action must not be
|
|
overridden.</em>
|
|
|
|
==== Direct dispatching example
|
|
|
|
class PersonController < ApplicationController
|
|
web_service_api PersonAPI
|
|
|
|
def add
|
|
end
|
|
|
|
def remove
|
|
end
|
|
end
|
|
|
|
class PersonAPI < ActionWebService::API::Base
|
|
...
|
|
end
|
|
|
|
|
|
For this example, protocol requests for +Add+ and +Remove+ methods sent to
|
|
<tt>/person/api</tt> will be routed to the actions +add+ and +remove+.
|
|
|
|
|
|
=== Delegated dispatching
|
|
|
|
This mode can be turned on by setting the +web_service_dispatching_mode+ option
|
|
in a controller.
|
|
|
|
In this mode, the controller contains one or more web service objects (objects
|
|
that implement an ActionWebService::API::Base definition). These web service
|
|
objects are each mapped onto one controller action only.
|
|
|
|
==== Delegated dispatching example
|
|
|
|
class ApiController < ApplicationController
|
|
web_service_dispatching_mode :delegated
|
|
|
|
web_service :person, PersonService.new
|
|
end
|
|
|
|
class PersonService < ActionWebService::Base
|
|
web_service_api PersonAPI
|
|
|
|
def add
|
|
end
|
|
|
|
def remove
|
|
end
|
|
end
|
|
|
|
class PersonAPI < ActionWebService::API::Base
|
|
...
|
|
end
|
|
|
|
|
|
For this example, all protocol requests for +PersonService+ are
|
|
sent to the <tt>/api/person</tt> action.
|
|
|
|
The <tt>/api/person</tt> action is generated when the +web_service+
|
|
method is called. <em>This action must not be overridden.</em>
|
|
|
|
Other controller actions (actions that aren't the target of a +web_service+ call)
|
|
are ignored for ActionWebService purposes, and can do normal action tasks.
|
|
|
|
|
|
== Using the client support
|
|
|
|
Action Web Service includes client classes that can use the same API
|
|
definition as the server. The advantage of this approach is that your client
|
|
will have the same support for Active Record and structured types as the
|
|
server, and can just use them directly, and rely on the marshaling to Do The
|
|
Right Thing.
|
|
|
|
*Note*: The client support is intended for communication between Ruby on Rails
|
|
applications that both use Action Web Service. It may work with other servers, but
|
|
that is not its intended use, and interoperability can't be guaranteed, especially
|
|
not for .NET web services.
|
|
|
|
Web services protocol specifications are complex, and Action Web Service client
|
|
support can only be guaranteed to work with a subset.
|
|
|
|
|
|
==== Factory created client example
|
|
|
|
class BlogManagerController < ApplicationController
|
|
web_client_api :blogger, :xmlrpc, 'http://url/to/blog/api/RPC2', :handler_name => 'blogger'
|
|
end
|
|
|
|
class SearchingController < ApplicationController
|
|
web_client_api :google, :soap, 'http://url/to/blog/api/beta', :service_name => 'GoogleSearch'
|
|
end
|
|
|
|
See ActionWebService::API::ActionController::ClassMethods for more details.
|
|
|
|
==== Manually created client example
|
|
|
|
class PersonAPI < ActionWebService::API::Base
|
|
api_method :find_all, :returns => [[Person]]
|
|
end
|
|
|
|
soap_client = ActionWebService::Client::Soap.new(PersonAPI, "http://...")
|
|
persons = soap_client.find_all
|
|
|
|
class BloggerAPI < ActionWebService::API::Base
|
|
inflect_names false
|
|
api_method :getRecentPosts, :returns => [[Blog::Post]]
|
|
end
|
|
|
|
blog = ActionWebService::Client::XmlRpc.new(BloggerAPI, "http://.../xmlrpc", :handler_name => "blogger")
|
|
posts = blog.getRecentPosts
|
|
|
|
|
|
See ActionWebService::Client::Soap and ActionWebService::Client::XmlRpc for more details.
|
|
|
|
== Dependencies
|
|
|
|
Action Web Service requires that the Action Pack and Active Record are either
|
|
available to be required immediately or are accessible as GEMs.
|
|
|
|
It also requires a version of Ruby that includes SOAP support in the standard
|
|
library. At least version 1.8.2 final (2004-12-25) of Ruby is recommended, this
|
|
is the version tested against.
|
|
|
|
|
|
== Download
|
|
|
|
The latest Action Web Service version can be downloaded from
|
|
http://rubyforge.org/projects/actionservice
|
|
|
|
|
|
== Installation
|
|
|
|
You can install Action Web Service with the following command.
|
|
|
|
% [sudo] ruby setup.rb
|
|
|
|
|
|
== License
|
|
|
|
Action Web Service is released under the MIT license.
|
|
|
|
|
|
== Support
|
|
|
|
The Ruby on Rails mailing list
|
|
|
|
Or, to contact the author, send mail to bitserf@gmail.com
|
|
|