{"id":23578591,"url":"https://github.com/dnault/therapi-json-rpc","last_synced_at":"2025-06-28T12:37:12.299Z","repository":{"id":32785702,"uuid":"36377785","full_name":"dnault/therapi-json-rpc","owner":"dnault","description":"Microframework for self-describing JSON-RPC2 APIs","archived":false,"fork":false,"pushed_at":"2021-02-21T21:58:02.000Z","size":866,"stargazers_count":8,"open_issues_count":7,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-05T23:52:33.291Z","etag":null,"topics":["java","json-rpc","json-rpc-api","json-rpc-client","json-rpc-server","json-rpc2"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnault.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.txt","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-27T15:48:42.000Z","updated_at":"2023-11-22T20:12:46.000Z","dependencies_parsed_at":"2022-08-25T14:51:29.842Z","dependency_job_id":null,"html_url":"https://github.com/dnault/therapi-json-rpc","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/dnault/therapi-json-rpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-json-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-json-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-json-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-json-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnault","download_url":"https://codeload.github.com/dnault/therapi-json-rpc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnault%2Ftherapi-json-rpc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262432407,"owners_count":23310240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","json-rpc","json-rpc-api","json-rpc-client","json-rpc-server","json-rpc2"],"created_at":"2024-12-26T22:39:41.350Z","updated_at":"2025-06-28T12:37:12.283Z","avatar_url":"https://github.com/dnault.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Build Self-Describing JSON-RPC 2.0 APIs with Therapi\n\n[![Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n![Java 1.8+](https://img.shields.io/badge/java-1.8+-lightgray.svg)\n\n## Why should I consider Therapi?\n\nMaintaining redundant API documentation is putting you on edge.\nArguing about which HTTP verb to use for partial updates is tearing your family apart.\nWhen you were at school, Swagger bullied you into doing things you'd rather not talk about.\n\nRelax. Everything is going to be okay. We'll work through this together.\n\n\n## Maven Coordinates\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.github.therapi\u003c/groupId\u003e\n  \u003cartifactId\u003etherapi-json-rpc\u003c/artifactId\u003e\n  \u003cversion\u003e0.4.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## No, really, what is this?\n\nTherapi is a Java microframework for exposing backend services\nover [JSON-RPC 2.0](http://www.jsonrpc.org/specification). It automatically\nbuilds interactive API documentation from Javadoc on your services classes.\n\nRight now it supports method invocations over HTTP. If you're willing\nto get your hands dirty, it could be adapted to work with WebSockets as well.\n\nTherapi plays well with Spring, and works fine on its own too. \n\n\n## The 3 minute cure\n\nIf you're in a hurry and don't want to deploy the example webapp locally,\nspeed over to the\n[live example webapp](https://therapi-json-rpc-demo.appspot.com) hosted on Google App Engine.\n\nWhile you're there, make sure to explore the\n[interactive API documentation](https://therapi-json-rpc-demo.appspot.com/jsonrpc/apidoc).\nEverything you see there was generated automatically\nfrom Javadoc in the source code. Each method has a \"Try It!\" button\n(clicking is recommended, and therapeutic).\n\nIf you'd like to tinker, start by cloning this repository and deploying the examples locally:\n\n    ./gradlew appRunWar\n\nThen visit [http://localhost:8080/examples](http://localhost:8080/examples). \n\n    \nThere's also a Spring Boot flavor which you can run with `./gradlew bootRun`\nand visit at a slightly different URL: [http://localhost:8080](http://localhost:8080)\n\n\n## Welcome to Therapi\n\nHave a seat on the couch over there. Put your feet up if it makes you feel comfortable. \nIf you're ready, let's begin.\n\n\n```java\npublic class GreetingService {    \n    /**\n     * Starts a conversation.\n     *\n     * @param name The name of the person to greet\n     * @return A friendly greeting message\n     */\n    public String greet(String name) {\n        return \"Hello, \" + name + \"!\";\n    }\n}\n```\n\nAs you can see, this is a complex service typical of many Fortune 500 Enterprise deployments.\nLet's make some money by sharing this service with the world using\nTherapi's `@Remotable` annotation.\n\n```java\nimport com.github.therapi.core.annotation.*;\n \n@Remotable(\"greeting\") // [1]\npublic class GreetingService {    \n    /**\n     * Starts a conversation.\n     *\n     * @param name The name of the person to greet\n     * @return A friendly greeting message\n     */\n    @Remotable // [2]\n    public String greet(@Default(\"stranger\") String name) { // [3]\n        return \"Hello, \" + name + \"!\";\n    }\n}\n```\n\n1. When applied to a class, `@Remotable` means the class should be scanned for\nremotable methods. It also assigns a namespace for those methods.\n2. When applied to a method, `@Remotable` indicates the method should be\nincluded in the exposed API.\n3. Therapi's `@Default` annotation makes it okay if non-confrontational clients\ndon't want to put up an argument.\n\nOnly `@Remotable` methods will be included in your API, and only `@Remotable` classes\nwill be scanned for remotable methods. \n\n\u003e When an interface is `@Remotable`, all of the methods defined by the interface\n\u003e are implicitly `@Remotable`, and so are any classes that implement the interface. \n\nIf you're using Spring, annotate the class with `@Service` and place it in a package\nwith component scanning enabled (`com.github.therapi.example.boot` for example).\nRestart the webapp, and your new method\nshould appear in the API documentation, ready to be invoked.\n\nWithout Spring, you'll need to manually instantiate the service and register it with Therapi.\nIn `ExampleJsonRpcServlet`, create an instance of your service class and pass\nit to the `scan` method of the `MethodRegistry`. Restart the webapp and play.\n\n\n## Compilation complications\n\nTherapi works best when method parameter names are available at runtime.\nMake sure to specify the `-parameters` option when running the java compiler,\notherwise your parameters will be named `arg0`, `arg1`, and so on.\n\nIn order for Javadoc to be available at runtime, annotation processing must be enabled\nduring compilation, with the `therapi-runtime-javadoc-scribe` annotation processor in the\ncompiler's processor path.\n\nBoth of these details are handled by the example build scripts, but when running\nfrom an IDE you may need to tweak your settings for best results. \n \nFor IntelliJ IDEA, go to `Preferences \u003e Build, Execution, Deployment \u003e Compiler`.\nUnder `Java Compiler`, set \"Additional command line parameters\" to `-parameters`.\nUnder `Annotation Processors`, select \"Enable annotation processing\" and \n\"Obtain processors from project class path\".\n\n\u003e For painless development and debugging, try running the\n\u003e `com.github.therapi.example.boot.Application` class from the\n\u003e `spring-boot-example` sub-project in your IDE.\n\n\n## You know what the music means...\n\nThere's a bit more documentation [over here](http://dnault.github.io/therapi-json-rpc/).\n\nSome other features to explore on your own:\n\n* The Boot webapp in `spring-boot-example` and the vanilla webapp in `examples` have different\nexample services. Try running them both. But not at the same time, unless you like port conflicts.\n* Use complex model classes as method arguments (anything Jackson can serialize/deserialize is supported). \n* Wrap method invocations with AOP interceptors (see `MethodRegistry.intercept`).\n* Generate a Java client for your API from a `@Remotable` interface (see `ServiceFactory`). \n* Customize how Therapi converts exceptions into JSON-RPC errors (see `ExceptionTranslator`).\n* Add example models to the documentation (see `@ExampleModel`).\n* Use the `@Default` annotation to provide a default value for any argument type that can be bound to JSON.\n* Annotate parameters as `@Nullable` to allow null values.\n* Annotate methods with `@DoNotLog` to suppress logging of sensitive requests/responses.\n* Customize the Jackson ObjectMapper (See `MethodRegistry` constructors).\n* When applying the `@Remotable` annotation to a method, specify a value to give the method a different name in the API.\n* Omit the value when applying `@Remotable` to a class or service to use a default name.\n\n## Credits\n\nTherapi includes software developed by the following third parties.\n\n* [json-forms](https://github.com/brutusin/json-forms) (Apache License 2.0) Ignacio del Valle Alles and contributors \n* [highlight](https://highlightjs.org) (BSD License) Copyright (c) 2006, Ivan Sagalaev\n* [jquery.jsonrpc](https://github.com/datagraph/jquery-jsonrpc) (Public Domain) Josh Huckabee, Chris Petersen, Jerry Ablan \n* [es6-promise.js](https://github.com/stefanpenner/es6-promise) (MIT License) Copyright (c) 2014 Yehuda Katz, Tom Dale, Stefan Penner and contributors\n* [Elegant Accordion Menu](http://cssmenumaker.com/menu/elegant-accordion-menu) by Russell Taylor\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnault%2Ftherapi-json-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnault%2Ftherapi-json-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnault%2Ftherapi-json-rpc/lists"}