JSON-RPC2 Ruby Server

A Rack compatible, documenting JSON-RPC 2 DSL/server implementation for ruby.

• Inline documentation
• Type checking for parameters and return values
• Authentication support - including HTTP Basic Authentication
• Rack mountable
• Interactive browser based API testing

class Calculator < JSONRPC2::Interface
  title "JSON-RPC2 Calculator"
  introduction "This interface allows basic maths calculations via JSON-RPC2"
  auth_with JSONRPC2::BasicAuth.new({'apiuser' => 'secretword'})

  section 'Simple Ops' do
      desc 'Multiply two numbers'
      param 'a', 'Number', 'First number'
      param 'b', 'Number', 'Second number'
      result 'Number', 'a * b'
      def mul args
        args['a'] * args['b']
      end

      desc 'Add numbers'
      param 'a', 'Number', 'First number'
      param 'b', 'Number', 'Second number'
      optional 'c', 'Number', 'Third number'
      example 'Calculate 1 + 1', :params => { 'a' => 1, 'b' => 1}, :result => 2
      result 'Number', 'a + b + c'
      def sum args
        val = args['a'] + args['b']
        val += args['c'] if args['c']
        val
      end
  end
end

To run example:

$ gem install shotgun # unless it's already installed
$ shotgun example/config.ru

Browse API and test it via a web browser at http://localhost:9393/

Use built in helper methods to declare complex types and function parameters before defining method calls.

e.g.

type "Address" do |t|
  t.string "street", "Street name"
  t.string "city", "City"
  ...
end

type "Person" do |t|
  t.string "name", "Person's name"
  t.number "age", "Person's age"
  t.boolean "is_member", "Is person a member of our club?"
  t.optional do
    t.field "address", "Address", "Address of person"
  end
end

Declare a JSON object type with named keys and value types

Describes the members of a JSON object - fields can be of any known type (see {JSONRPC2::Types} for details).

Use blocks to specify whether an object field is required or optional

e.g.

     desc 'Add numbers'
     param 'a', 'Number', 'First number'
     param 'b', 'Number', 'Second number'
     optional 'c', 'Number', 'Third number'
     example 'Calculate 1 + 1', :params => { 'a' => 1, 'b' => 1}, :result => 2
     result 'Number', 'a + b + c'
     def sum args
       val = args['a'] + args['b']
       val += args['c'] if args['c']
       val
     end

Short description of what the method does

or

Description of a named parameter for the method, including type and purpose (see {JSONRPC2::Types} for type details)

Type and description of return value for method (see {JSONRPC2::Types} for type details)

Describe example usage

Describe example usage and valid result (NB: values specified for both params and result are checked against the method type descriptions and generating docs will throw an error if the values are invalid).

Describe example usage and sample error (NB: values specified for params are checked against the method type descriptions and generating docs throws an error if the values are invalid).

Don't include next method in documentation

e.g.

title "Calculator interface"
introduction "Very simple calculator interface"

section "Entry points" do
  ...
end

Set title for interface

Add a basic introduction for the API

Group methods into logical sections for documentation purposes

e.g. auth_with JSONRPC2::BasicAuth.new({'apiuser' => 'secretword'})

Specify authentication method that should be used to verify the access credentials before printing. See {JSONRPC2::BasicAuth} for examples/info.

• Run bin/setup to build a local docker image
• Run bin/test to run the test suite
• Run bin/run-example to run the example JSONRPC API from within docker container