Skip to content

Extension Documentation

Jump to bottom
spmallette edited this page May 20, 2011 · 13 revisions

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.

Hypermedia

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.

API Documentation

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: parameter descriptions, explicit description and a combination of the two.

Parameter Description

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.

Explicit Description

If for some reason the extension is not using @ExtensionRequestParameter annotations (perhaps the extension simply extracts the extension parameters from one of the context objects directly), the extension can provide its documentation directly through the @ExtensionDescriptor annotation. Simply supply an array of @ExtensionApi annotations to the api parameter of the @ExtensionDescriptor.

Given the following sample:

@ExtensionDescriptor(description = "some extension i wrote for gremlin",
                     api = {
                         @ExtensionApi(parameterName = "script", description = "the Gremlin script to be evaluated"),
                         @ExtensionApi(parameterName = "xyz", description = "a fake parameter")
                     })

the returned JSON with api attribute would look like:

{
  "message":null,
  "api":{
    "description":"some extension i wrote for gremlin",
    "parameters":[
      {"script":"the Gremlin script to be evaluated"}, 
      {"xyz":"a fake parameter"}
    ]
  },
  "success":false}

Combined

It is possible to use both the parameter-based description as well as the explicit description together. By default, Rexster will try to use explicit description first and the override existing keys with values from the parameter description first. That behavior can be controlled by setting the apiBehavior property on the @ExtensionDescriptor annotation.

Clone this wiki locally