1# What Is RESTinio? 2 3RESTinio is a header-only C++14 library that gives you an embedded 4HTTP/Websocket server. It is based on standalone version of ASIO 5and targeted primarily for asynchronous processing of HTTP-requests. 6Since v.0.4.1 Boost::ASIO (1.66 or higher) is also supported 7(see [notes on building with Boost::ASIO](https://stiffstream.com/en/docs/restinio/0.6/obtaining.html#notes-on-building-with-boost-asio)). 8 9# A Very Basic Example Of RESTinio 10 11Consider the task of writing a C++ application that must support some REST API, 12RESTinio represents our solution for that task. Currently it is in stable beta state. 13Lets see how it feels like in the simplest case: 14 15```C++ 16#include <restinio/all.hpp> 17int main() 18{ 19 restinio::run( 20 restinio::on_this_thread() 21 .port(8080) 22 .address("localhost") 23 .request_handler([](auto req) { 24 return req->create_response().set_body("Hello, World!").done(); 25 })); 26 return 0; 27} 28``` 29 30Server runs on the main thread, and respond to all requests with hello-world 31message. Of course you've got an access to the structure of a given HTTP request, 32so you can apply a complex logic for handling requests. 33 34# Features 35 36* Async request handling. Cannot get the response data immediately? That's ok, 37 store request handle somewhere and/or pass it to another execution context 38 and get back to it when the data is ready. 39* HTTP pipelining. Works well with async request handling. 40 It might increase your server throughput dramatically. 41* Timeout control. RESTinio can take care of bad connection that are like: send 42 "GET /" and then just stuck. 43* Response builders. Need chunked-encoded body - then RESTinio has a special 44 response builder for you (obviously it is not the only builder). 45* ExpressJS-like request routing (see an example below). 46* An experimental typesafe request router that allows avoiding problems of ExpressJS-like router with help of static checks from C++ compiler. 47* A possibility to chain several request-handlers (somewhat similar to ExpressJS's middleware). 48* Working with query string parameters. 49* Several ready-to-use helpers for working with HTTP headers (for example, the support for HTTP headers related to file uploading). 50* Supports sending files and its parts (with sendfile on linux/unix and TransmitFile on windows). 51* Supports compression (deflate, gzip). 52* Supports TLS (HTTPS). 53* Basic websocket support. Simply restinio::websocket::basic::upgrade() the 54 request handle and start websocket session on a corresponding connection. 55* Can run on external asio::io_context. RESTinio is separated from execution 56 context. 57* Some tune options. One can set acceptor and socket options. When running 58 RESTinio on a pool of threads connections can be accepted in parallel. 59 60# Enhanced Example With Express Router 61 62```C++ 63#include <restinio/all.hpp> 64 65using namespace restinio; 66 67template<typename T> 68std::ostream & operator<<(std::ostream & to, const optional_t<T> & v) { 69 if(v) to << *v; 70 return to; 71} 72 73int main() { 74 // Create express router for our service. 75 auto router = std::make_unique<router::express_router_t<>>(); 76 router->http_get( 77 R"(/data/meter/:meter_id(\d+))", 78 [](auto req, auto params) { 79 const auto qp = parse_query(req->header().query()); 80 return req->create_response() 81 .set_body( 82 fmt::format("meter_id={} (year={}/mon={}/day={})", 83 cast_to<int>(params["meter_id"]), 84 opt_value<int>(qp, "year"), 85 opt_value<int>(qp, "mon"), 86 opt_value<int>(qp, "day"))) 87 .done(); 88 }); 89 90 router->non_matched_request_handler( 91 [](auto req){ 92 return req->create_response(restinio::status_not_found()).connection_close().done(); 93 }); 94 95 // Launching a server with custom traits. 96 struct my_server_traits : public default_single_thread_traits_t { 97 using request_handler_t = restinio::router::express_router_t<>; 98 }; 99 100 restinio::run( 101 restinio::on_this_thread<my_server_traits>() 102 .address("localhost") 103 .request_handler(std::move(router))); 104 105 return 0; 106} 107``` 108 109# License 110 111RESTinio is distributed under BSD-3-CLAUSE license. 112 113# How To Use It? 114 115The full documentation for RESTinio can be found [here](https://stiffstream.com/en/docs/restinio/0.6/). 116 117# More 118 119* Issues and bugs: 120[Issue Tracker on GitHub](https://github.com/stiffstream/restinio/issues). 121* Discussion section [on GitHub](https://github.com/Stiffstream/restinio/discussions). 122* Discussion group: [restinio](https://groups.google.com/forum/#!forum/restinio). 123 124