Project

jsonrpc2

0.0
No commit activity in last 3 years
No release in over 3 years
== Description A Rack compatible JSON-RPC2 server domain specific language (DSL) - allows JSONRPC APIs to be defined as mountable Rack applications with inline documentation, authentication and type checking. e.g. class Calculator < JSONRPC2::Interface title "JSON-RPC2 Calculator" introduction "This interface allows basic maths calculations via JSON-RPC2" auth_with JSONRPC2::BasicAuth.new({'user' => 'secretword'}) section 'Simple Ops' do desc 'Multiply two numbers' param 'a', 'Number', 'a' param 'b', 'Number', 'b' result 'Number', 'a * b' def mul args args['a'] * args['b'] end desc 'Add numbers' example "Calculate 1 + 1 = 2", :params => { 'a' => 1, 'b' => 1}, :result => 2 param 'a', 'Number', 'First number' param 'b', 'Number', 'Second number' optional 'c', 'Number', 'Third number' result 'Number', 'a + b + c' def sum args val = args['a'] + args['b'] val += args['c'] if args['c'] val end end end
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies

Runtime

 Project Readme

JSON-RPC2 Ruby Server

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

Changes

  • 0.1.1 - 4-Jan-2013 Improve logging of exceptions / failure

  • 0.1.0 - 4-Jan-2013 Turn on timing & logging of all requests

  • 0.0.9 - 3-Sep-2012 Improve client validation Make params optional in request call

  • 0.0.8 - 3-Sep-2012 Add #request to access Rack::Request object Make URLs in HTML interface clickable

  • 0.0.7 - 27-Aug-2012 Add bundled Bootstrap assets for HTML test interface

  • 0.0.6 - 24-Aug-2012 Add Date/Time/DateTime as special string types with regex checks for validation

  • 0.0.5 - 19-Jul-2012 Add commandline client jsonrpc2 Add #auth to access currently authenticated username

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.