JSchema-RPC

"The enemy of art is the absence of limitations."

Introduction

To complement JSchema, JSchema-RPC is a way to specify a RPC end point using JSON.

RPC URL Convention and File Conventions

Given an end point at:

http://example.com/path/

The JSchema-RPC should be available at:

http://example.com/path/?JSchema-RPC

Locally, JSchema-RPC files should end with the .jsc-rpc file suffix.

Grammar

The grammar for a JSchema-RPC file builds on the grammar for JSchema and JSON:

<rpc> ::= 
    '{'
      '"url"' ':' <string> 
      <optional_description>
      <optional_typedefs>
      '"functions"' ':' '[' <function_specs> ']'
    '}'
  
<optional_description>
    '' |
    ',' '"description"' ':' <string> ',' 

<optional_typedefs>
    '' |
    ',' <typedefs_map>

<function_specs> ::= 
    '' |
    <function_spec> | 
    <function_spec> ',' <function_specs> 

<function_spec> ::= 
    '{' '"name"' ':' <string>
      <optional_description>
      <optional_args_spec>
      <optional_return_type>
    '}'

<optional_args_spec> ::=
    '' |
    ',' '"args"' ':' '[' <arg_specs> ']'

<arg_specs> ::=
    '' |
    <arg_spec> |
    <arg_spec> ',' <arg_specs>
  
<arg_spec> ::=
  '{' <string> ':' <type> <optional_default> <optional_description> '}'

<optional_default> ::=
  ',' '"default"' ':' <object> |
  ''
<optional_return_type> ::=
    ',' '"returns"' ':' <type> |
    ''

Implementation Notes

All functions must have unique names.
Note that arguments and return values are not necessarily JSON documents: they may be JSON document fragments corresponding to JSchema types.
If a function does not specify a return value, it is interpreted as being a 'void' function.
If a function does not specify an argument list, it is interpreted as having no arguments.
The 'self' type is not supported in JSchema-RPC files.
JSchema-RPC is explicitly silent on things like authentication, which should be handled at the protocol or application level.

Invocation

Given a JSchema-RPC Document and a function specification, invocation of the function is done as follows:

The "name" of the function will be appended to the "url" (or a different URL if the user has specified one) using the separator appropriate for the protocol
The arguments will be passed by name in a manner appropriate for the scheme specified in the composed URL. In the case of http/https, this will be either as a query string or as post variables as a GET or POST, respectively. If an argument is not included it will be interpreted as 'null' unless a default value is specified.
The return content will conform to the type specified as the "return_type" unless an exception is returned, in which case it will conform to the grammar specified in the "Exceptions" section.

Exceptions

Exceptions may be raised by a JSchema-RPC end point using a return value of the following form:

<jschema_rpc_exception> ::= 
  '{'
    '"exception@"' ':' <string> <optional_type> <optional_trace>
  '}'

<optional_type> ::=  
  '' | 
  ',' '"exception_type@"' ':' <string>    

<optional_trace> ::=  
  '' | 
  ',' '"trace@"' ':' <string>

End point creators should strive to provide useful traces, including elements only relevant to the remote procedure, rather than implementation details of the invocation.

The optional 'exception_type@' element is only a hint to the client. Client implementations should make a best effort to produce an equivalent exception on their side, but there are no guarantees regarding the type of exception produced.

Examples

JSchema-RPC File	Example usage (Gosu)
{ "url" : "http://myserver:8080/employees", "description" : "Methods for manipulating employees", "typedefs@" : { "Employee" : { "first_name" : "string", "last_name" : "string", "age" : "int", "id" : "int" } }, "functions" : [ { "name" : "getEmployee", "description" : "Returns the employee with the given id", "args" : [ {"id" : "int" } ], "returns" : "Employee" }, { "name" : "updateEmployee", "description" : "Updates the given employee", "args" : [ { "employee" : "Employee" } ], "returns" : "boolean" } ] }	// Assuming the above file is in EmployeesApi.jsc-rpc: var myEmp = EmployeesApi.getEmployee(42) myEmp.Age++ if( EmployeesApi.updateEmployee(myEmp) ) { print( "Updated the age of ${myEmp.FirstName}") }

JSchema-RPC File

Example usage (Gosu)

{ "url" : "http://myserver:8080/employees", "description" : "Methods for manipulating employees", "typedefs@" : { "Employee" : { "first_name" : "string", "last_name" : "string", "age" : "int", "id" : "int" } }, "functions" : [ { "name" : "getEmployee", "description" : "Returns the employee with the given id", "args" : [ {"id" : "int" } ], "returns" : "Employee" }, { "name" : "updateEmployee", "description" : "Updates the given employee", "args" : [ { "employee" : "Employee" } ], "returns" : "boolean" } ] }

// Assuming the above file is in EmployeesApi.jsc-rpc: var myEmp = EmployeesApi.getEmployee(42) myEmp.Age++ if( EmployeesApi.updateEmployee(myEmp) ) { print( "Updated the age of ${myEmp.FirstName}") }