-
Notifications
You must be signed in to change notification settings - Fork 116
Extension Documentation
Rexster helps provide API documentation to users of the extension in two ways. First, Rexster will show what extensions are properly configured and available from a particular URI as well as how to access them. Second, Rexster can display API documentation for a specific service as part of error message generation.
When accessing a URI extension point, the list of properly configured extensions will be displayed. Accessing this URI with the "Sample Kibbles:https://github.com/tinkerpop/rexster-kibbles/tree/master/sample-kibbles configured:
http://localhost:8182/tinkergraph/
will yield:
{
"version":"0.4-SNAPSHOT",
"name":"tinkergraph",
"graph":"tinkergraph[vertices:6 edges:6]",
"readOnly":false,
"type":"com.tinkerpop.blueprints.pgm.impls.tg.TinkerGraph",
"queryTime":0.955418,
"upTime":"0[d]:00[h]:13[m]:24[s]",
"extensions":[
{"title":"evaluate an ad-hoc Gremlin script for a graph.","href":"tp\/gremlin"},
{"title":"returns the configuration as JSON.","href":"tp-sample\/map-config"},
{"title":"a simple ping extension.","href":"tp-sample\/ping"},
{"title":"returns the results of the toString() method on the graph.","href":"tp-sample\/simple-path\/some-work"},
{"title":"returns the results of the toString() method on the edge.","href":"tp-sample\/simple-path\/other-work"},
{"title":"returns the results of the toString() method on the graph.","href":"tp-sample\/simple-root"}
]
}
Note that extensions
attribute which contains an array of configured extensions. The value for the title
property comes from the value of the description
parameter supplied to @ExtensionDescriptor
. The href
property defines the relative path to that extension from that base URI.
In the event that the extension is not properly configured in some way, it will not appear in this list.
When a failure occurs, it is nice to show to the user what the expectations are for the extension and its basic API. Rexster helps with this in a few ways. First of all, a description
parameter can be supplied to the ExtensionRequestParameter
. Consider this code snippet from the PingExtension
in the Sample Kibbles project:
public ExtensionResponse evaluatePing(@RexsterContext RexsterResourceContext context,
@RexsterContext Graph graph,
@ExtensionRequestParameter(name="reply", description="a value to reply with") String reply)
When accessing the following URI (forgetting to include the reply
URI query string parameter):
http://localhost:8182/tinkergraph/tp-sample/ping
Rexster will provide the following response:
{
"message":"the reply parameter cannot be empty",
"api":{
"description":"a simple ping extension.",
"parameters":{"reply":"a value to reply with"}
},
"success":false}
Note that the reply
parameter is injected into the api.parameters
along with the value from the description
parameter. It is possible to get the api
JSON fragment from the ExtensionMethod
using the getExtensionApiAsJson
method.