https://github.com/esensar/neovim-http-api-plugin
Very simple HTTP wrapper around Neovim RPC API - demonstration of neovim-java-plugin-host - Moved to https://codeberg.org/neovim-java/neovim-http-api-plugin
https://github.com/esensar/neovim-http-api-plugin
api http java neovim neovim-java-plugin plugin rpc
Last synced: 4 months ago
JSON representation
Very simple HTTP wrapper around Neovim RPC API - demonstration of neovim-java-plugin-host - Moved to https://codeberg.org/neovim-java/neovim-http-api-plugin
- Host: GitHub
- URL: https://github.com/esensar/neovim-http-api-plugin
- Owner: esensar
- License: mit
- Created: 2022-06-08T13:59:58.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-06-10T10:40:01.000Z (over 3 years ago)
- Last Synced: 2025-10-10T10:08:56.150Z (4 months ago)
- Topics: api, http, java, neovim, neovim-java-plugin, plugin, rpc
- Language: Java
- Homepage:
- Size: 80.1 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Neovim HTTP API
This plugin serves as an example of Java plugin that can be used with [neovim-java-plugin-host](https://github.com/esensar/neovim-java-plugin-host). It provides Neovim RPC API through HTTP endpoints.
**NOTE:** This example uses request instead of notification for starting. In this case, notification could have been used as well (and is probably the better solution, since it won't block Neovim). To use notifications instead `@NeovimNotificationHandler` annotation should be used, and from neovim `notify` instead of `request` should be used.
## Requirements
- [Neovim](https://neovim.io/) version 0.7.0+
- [neovim-java-plugin-host](https://github.com/esensar/neovim-java-plugin-host)
## Usage
### Installation
There are a couple of different ways to install the plugin.
#### Plugin manager
Using your favourite plugin manager, e.g. [Packer.nvim](https://github.com/wbthomason/packer.nvim):
```lua
use {
'esensar/neovim-http-api-plugin',
requires = { 'esensar/neovim-java-plugin-host' },
run = { 'mkdir -p rplugin/hosted-jar && mvn package && cp target/*.jar rplugin/hosted-jar/' }
}
```
For this way to work, `require("java_plugin_host").setup()` needs to be called and `rplugins.load_hosted` needs to be true (it is true by default). This is one of the easiest ways to install the plugin and it also supports any custom documentation added in `doc/` directory.
#### Java plugin host
If `esensar/neovim-java-plugin-host` is already installed and used, this plugin can be added to its configuration (in this case JAR will be downloaded from specified repository):
```lua
require("java_plugin_host").setup {
-- ...
common_host = {
-- ...
hosted_plugins = {
-- ...
{
group_id = "com.ensarsarajcic.neovim.http",
artifact_id = "neovim-http-api-plugin",
version = "0.1.0"
},
-- ...
},
custom_repositories = {
-- ...
-- This is optional in case of this plugin, since it is also deployed to maven central
-- But usually, this provides an easier way for plugin authors to deploy their plugins, directly to GitHub package repository
{
id = "github",
url = "https://maven.pkg.github.com/esensar/neovim-http-api-plugin"
}
-- ...
}
-- ...
}
-- ...
}
```
**NOTE**: To use custom repositories (GitHub), [GitHub Packages Auth](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) needs to be set up.
### Starting the API
API can be started with a request, that can be made using `java_plugin_host`:
```lua
require("java_plugin_host").request(
"com.ensarsarajcic.neovim.http.NeovimHttpApi.start",
{
-- Port is required!
port = 8080,
-- Optionally define thread count for HTTP handler
-- thread_count = 4,
-- Optionally define root URL
-- root_url = "/",
-- Optionally define request timeout in millisecond
-- request_timeout_ms = 10000
}
)
```
After this API should be available on `http://localhost:8080`.
### Calling the API
Example calls:
```
curl "http://localhost:8080?opts.builtin=false"
{"AbortDispatch":{"name":"AbortDispatch","definition":"execute dispatch#abort_command(0, )","script_id":84,"bang":true,"bar":true,"register":false,"keepscript":false,"nargs":"*","complete":null,"complete_arg":null,"count":null,"range":null,"addr":null},"...}
curl "http://localhost:8080/buf/0/name"
"/home/user/.cache/nvim/java_plugin_host/common_host.log"
curl "http://localhost:8080/buf/0/name" -X PUT -d '{"name": "new_name"}'
null
curl "http://localhost:8080/buf/0/name"
"/home/user/.cache/nvim/java_plugin_host/new_name"
```
API supports `GET`, `PUT`, `DELETE` and `POST` requests. Command name is generated by adding `nvim_` prefix to the request path, as well as additional prefix based on used method (`GET = get_`, `PUT = set_` and `DELETE = del_` - special case is `nvim_buf_delete`). Methods for buffers, windows and tabpages are supported as well, following the format:
```
http://localhost:8080/{buf,window,tabpage}/{id}/method_name
```
As seen in the example above - `http://localhost:8080/buf/0/name` = `nvim_get_buf_name` for buffer 0
Arguments can be passed in query params (suitable for `GET` requests) and body too. Body should be in JSON using names as defined by `nvim_get_api_info`, and query should use the same names, using `.` to set nested fields - example: `http://localhost:8080?opts.builtin=false`
## License
[MIT](LICENSE)