README.markdown

JSON-RPC2 Ruby Server

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

Features

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

Example

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/

Inline documentation

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

Custom type definitions

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

type "Name", &block

Declare a JSON object type with named keys and value types

field "Name", "Type", "Description"

string "Name", "Description"

number "Name", "Description"

integer "Name", "Description"

boolean "Name", "Description"

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

optional &block

required &block

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

---

Method annotations

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

desc "Description of method"

Short description of what the method does

param "Name", "Type", "Description"

or

optional "Name", "Type", "Description"

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

result "Type", "Description"

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

example "Description", "Detail"

Describe example usage

example "Description", { :params => { ... }, :result => value }

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).

example "Description", { :params => { ... }, :error => value }

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).

nodoc

Don't include next method in documentation

---

Interface annotations

e.g.

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

section "Entry points" do
  ...
end

title "Title"

Set title for interface

introduction "Introduction/description of interface"

Add a basic introduction for the API

section "Name", &block

Group methods into logical sections for documentation purposes

Authentication

auth_with Authenticator

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.

Development

• 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