Hi!

Welcome to the Therapi JSON-RPC example webapp. The JSON-RPC endpoint is here.

If this is your first visit, start by browsing the automatically generated documentation for the example services. The text you see on that page comes from Javadoc in the source code. The Javadoc was baked into the code using the therapi-runtime-javadoc annotation processor.

From the documentation you can press the "Try It!" buttons to invoke the service methods. This feature is still experimental; the generated form might not be absolutely perfect for all kinds of method signatures, but it should give you an idea of how to invoke the methods from a real Javascript client.

Speaking of Javascript clients...

There's also an automatically generated Javascript client library to play with. It uses the JSON RPC 2.0 jQuery Plugin in combination with Javascript dynamically generated by the server.

The Javascript client is embedded in this welcome page, so you can experiment from here if you like. Open the Javascript console and try this:

    // Print dictionary entries starting with "a"
    Therapi.dictionary.list("a").then(logit).catch(logit);

Or chain Promises together, like so:

    Therapi.dictionary.list()
        .then(function(words) {
            var randomWord = words[Math.floor(Math.random()*words.length)];
            console.debug(randomWord);
            return Therapi.dictionary.lookUp(randomWord);
        })
        .then(logit)
        .catch(logit);

You don't have to use the auto-generated client; since JSON-RPC is a standard protocol, you're free to use any client library you like.

Manual requests in a hurry

Therapi also supports a non-standard request format that makes it easy for developers to manually invoke methods from a browser's location bar. Here are some example links. After clicking them, check out your browser's location bar to see what the request URLs look like:

Diving deeper

When you're ready, take a look at the source code for the example services. To use Therapi JSON-RPC in your own traditional webapp, you'll need to create a subclass of AbstractJsonRpcServlet and register your services. Use the ExampleJsonRpcServlet class as a template. Don't forget to add your new servlet to web.xml (see this webapp's web.xml file for an example).

If you'd rather use Spring Boot, or if you want to wire Therapi into a Spring MVC application, check out the project in the spring-boot-example folder.

Some important things to remember:

Your service interfaces must be compiled with the -parameters option to javac so that parameter names are available at runtime.
If you want your Javadoc comments to be included in the API documentation, use the therapi-runtime-javadoc annotation processor when compiling your project.

The example build script build.gradle takes care of both of these items. Feel free to use it as a template.

Found a bug? Have a feature request? Let me know.

Okay, that's it. Have fun with Therapi!