Description
A Framework for Building HTTP API.
Description
Allows to easily create high-performance full featured HTTP APIs from R functions. Provides high-level classes such as 'Request', 'Response', 'Application', 'Middleware' in order to streamline server side application development. Out of the box allows to serve requests using 'Rserve' package, but flexible enough to integrate with other HTTP servers such as 'httpuv'.
README.md
RestRserve
RestRserve is an R web API framework for building high-performance AND robust microservices and app backends. On UNIX-like systems and Rserve backend RestRserve handles requests in parallel: each request in a separate fork - credits go to Simon Urbanek.
Quick start
Creating application is as simple as:
library(RestRserve)
app = Application$new()
app$add_get(
path = "/health",
FUN = function(.req, .res) {
.res$set_body("OK")
})
app$add_post(
path = "/addone",
FUN = function(.req, .res) {
result = list(x = .req$body$x + 1L)
.res$set_content_type("application/json")
.res$set_body(result)
})
backend = BackendRserve$new()
backend$start(app, http_port = 8080)
Test it with curl
:
curl localhost:8080/health
# OK
curl -H "Content-Type: application/json" -d '{"x":10}' localhost:8080/addone
# {"x":11}
Autocomplete
Using convenient .req
, .res
names for handler arguments allows to leverage autocomplete.
Learn RestRserve
- follow quick start guide on http://restrserve.org/ for more details.
- see "Articles" section on https://restrserve.org/
- check out examples on https://github.com/rexyai/RestRserve
Features
- Stable, easy to install, few dependencies
- Concise and intuitive syntax
- Well documented, comes with many examples - see inst/examples
- Fully featured http server with the support for URL encoded and multipart forms
- Build safe and secure applications - RestRserve supports https, provides building blocks for basic/token authentication
- Raise meaningful http errors and allows to interrupt request handling from any place of the user code
- Saves you from boilerplate code:
- automatically decodes request body from the common formats
- automatically encodes response body to the common formats
- automatically parses URI templates (such as
/get/{item_id}
) - helps to expose OpenAPI and Swagger/Redoc/Rapidoc UI
- It is fast!
Installation
From CRAN
install.packages("RestRserve", repos = "https://cloud.r-project.org")
Docker
Debian and Alpine based images are available on docker-hub -https://hub.docker.com/r/rexyai/restrserve/
docker pull rexyai/restrserve
You can also install specific version (and we encourage to do so):
docker pull rexyai/restrserve:1.2.0-alpine
Contributing
Guidelines for filing issues / pull requests - CONTRIBUTING.md.
Acknowledgements
- Simon Urbanek (@s-u) for awesome Rserve and all the work on R itself and on his other packages
- Jeff Allen (@trestletech) for his work on Swagger UI in plumber (from where we took inspiration for our implementation)
- Brodie Gaslam (@brodieG) for help with understanding on how to get traceback from try-catch function calls. Also thanks Hadley Wickham (@hadley) for
evaluate::try_capture_stack
function which we use for this purpose.
Known limitations
- RestRserve is primarily tested on UNIX systems. While it works natively on Windows please don't expect it to be as performant as on UNIX-like systems. If you really want to use it on Windows - consider to use Windows Subsystem for Linux.
- Keep in mind that every request is handled in a separate process (fork from a parent R session). While this feature allows to handle requests in parallel it also restricts reuse of certain objects which are not fork-safe (notably database connections, rJava objects, etc)