-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathrpc.html
164 lines (151 loc) · 5.23 KB
/
rpc.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
<html>
<head>
<title>JSchema-RPC</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<center>
<h1>JSchema-RPC</h1>
<p><i>"The enemy of art is the absence of limitations."</i></p>
<p> </p>
</center>
<h2>Introduction</h2>
<p>
To complement <a href="/">JSchema</a>, JSchema-RPC is a way to specify a RPC end point using JSON.
</p>
<h2>RPC URL Convention and File Conventions</h2>
<p>
Given an end point at: <pre>http://example.com/path/</pre> The JSchema-RPC should be available at: <pre>http://example.com/path/?JSchema-RPC</pre>
</p>
<p>
Locally, JSchema-RPC files should end with the <code>.jsc-rpc</code> file suffix.
</p>
<h2>Grammar</h2>
<p>
The grammar for a JSchema-RPC file builds on the grammar for JSchema and JSON:
<pre>
<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> |
''
</pre>
<h2>Implementation Notes</h2>
<ul>
<li>All functions must have unique names.</li>
<li>Note that arguments and return values are not necessarily JSON documents: they may be JSON document fragments corresponding to JSchema types.</li>
<li>If a function does not specify a return value, it is interpreted as being a 'void' function.</li>
<li>If a function does not specify an argument list, it is interpreted as having no arguments.</li>
<li>The 'self' type is not supported in JSchema-RPC files.</li>
<li>JSchema-RPC is explicitly silent on things like authentication, which should be handled at the protocol or application level.</li>
</ul>
<h2>Invocation</h2>
<p>
Given a JSchema-RPC Document and a function specification, invocation of the function is done as follows:
</p>
<ul>
<li>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</li>
<li>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.</li>
<li>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.</li>
</ul>
<h2>Exceptions</h2>
<p>
Exceptions may be raised by a JSchema-RPC end point using a return value of the following form:
<pre>
<jschema_rpc_exception> ::=
'{'
'"exception@"' ':' <string> <optional_type> <optional_trace>
'}'
<optional_type> ::=
'' |
',' '"exception_type@"' ':' <string>
<optional_trace> ::=
'' |
',' '"trace@"' ':' <string>
</pre>
End point creators should strive to provide useful traces, including elements only relevant to the remote procedure, rather than implementation details of the invocation.
</p>
<p>
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.
</p>
<h2>Examples</h2>
<table class="examples-table">
<tr>
<th>
JSchema-RPC File
</th>
<th>
Example usage (Gosu)
</th>
</tr>
<tr>
<td>
{ "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"
}
]
}
</td>
<td>
// 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}")
}
</td>
</tr>
<table>
</body>
</html>