oatpp/README.md

170 lines
7.4 KiB
Markdown
Raw Normal View History

2023-10-06 06:27:23 +08:00
[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://vshymanskyy.github.io/StandWithUkraine/)
---
2020-08-04 09:09:30 +08:00
<div align="center">
<img alt="Oat++ Logo" src="https://raw.githubusercontent.com/lganzzzo/oatpp-website-res/master/logo_x400.png" width="200px"/>
</div>
<p>&nbsp;</p>
<p align="center">
<a href="https://dev.azure.com/lganzzzo/lganzzzo/_build?definitionId=1">
<img src="https://dev.azure.com/lganzzzo/lganzzzo/_apis/build/status/oatpp.oatpp" alt="oatpp build status" />
</a>
<a href="https://gitter.im/oatpp-framework/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge">
<img src="https://badges.gitter.im/oatpp-framework/Lobby.svg" alt="Join the chat at https://gitter.im/oatpp-framework/Lobby" />
</a>
</p>
# Oat++
2018-03-13 12:04:53 +08:00
2020-10-27 09:31:30 +08:00
**News**
2020-09-29 07:10:38 +08:00
2024-04-22 04:18:43 +08:00
- ⚠️ Attention! Oat++ main repo is bumping it's version to 1.4.0. While 1.4.0 is **IN DEVELOPMENT** use `1.3.0-latest` tag.
2020-05-10 04:12:39 +08:00
---
2020-05-31 16:11:53 +08:00
Oat++ is a modern Web Framework for C++.
It's fully loaded and contains all necessary components for effective production level development.
It's also light and has a small memory footprint.
2018-10-18 07:54:45 +08:00
2020-05-31 16:11:53 +08:00
**Start**
2020-10-27 09:31:30 +08:00
2020-05-31 16:11:53 +08:00
- [Get Started](https://oatpp.io/docs/start/)
- [Build For Unix/Linux](https://oatpp.io/docs/installation/unix-linux/)
- [Build For Windows](https://oatpp.io/docs/installation/windows/)
2020-06-05 05:54:11 +08:00
- [Examples](#examples)
2020-05-31 16:11:53 +08:00
**About**
2020-10-27 09:31:30 +08:00
2019-05-10 02:42:34 +08:00
- [Website](https://oatpp.io/)
2019-10-28 10:09:56 +08:00
- [Supported Platforms](https://oatpp.io/supported-platforms/)
2019-05-20 10:16:00 +08:00
- Latest Benchmarks: [5 Million WebSockets](https://oatpp.io/benchmark/websocket/5-million/)
2020-05-31 16:11:53 +08:00
- [Contributing to Oat++](CONTRIBUTING.md)
2018-07-09 05:11:10 +08:00
2020-05-31 16:11:53 +08:00
**Join Our Community**
2018-10-14 17:49:59 +08:00
2020-10-27 09:31:30 +08:00
- [Gitter](https://gitter.im/oatpp-framework/Lobby) - Talk to Oat++ developers and to other Oat++ users.
- [Twitter](https://twitter.com/oatpp_io) - Follow Oat++ on Twitter.
- [Reddit](https://www.reddit.com/r/oatpp/) - Follow Oat++ subreddit.
- [StackOverflow (new)](https://stackoverflow.com/questions/tagged/oat%2b%2b) - Post a Question.
2018-10-14 17:49:59 +08:00
2020-10-27 09:31:30 +08:00
## Quick Overview
2018-10-14 17:49:59 +08:00
2020-10-27 09:31:30 +08:00
**Shortcuts:**
2018-10-14 17:49:59 +08:00
2020-10-27 09:31:30 +08:00
- [Oat++ High Level Overview](https://oatpp.io/docs/start/high-level-overview/) - Get a quick overview of Oat++ features.
- [Example Project](https://github.com/oatpp/example-crud) - A complete example of a "CRUD" service (UserService) built with Oat++. REST + Swagger-UI + SQLite.
2018-10-14 17:49:59 +08:00
2020-10-27 09:31:30 +08:00
### Build Powerful API And Document It With Swagger-UI
2018-10-14 17:49:59 +08:00
2020-10-27 09:31:30 +08:00
See [ApiController](https://oatpp.io/docs/components/api-controller/) for more details.
2018-10-14 17:49:59 +08:00
2019-10-28 10:09:56 +08:00
```cpp
2020-10-27 09:31:30 +08:00
ENDPOINT_INFO(getUserById) {
info->summary = "Get one User by userId";
2018-10-14 17:49:59 +08:00
2020-05-23 08:34:01 +08:00
info->addResponse<Object<UserDto>>(Status::CODE_200, "application/json");
2020-10-27 09:31:30 +08:00
info->addResponse<Object<StatusDto>>(Status::CODE_404, "application/json");
info->addResponse<Object<StatusDto>>(Status::CODE_500, "application/json");
2019-10-28 10:09:56 +08:00
info->pathParams["userId"].description = "User Identifier";
2018-10-15 16:49:04 +08:00
}
2020-10-27 09:31:30 +08:00
ENDPOINT("GET", "users/{userId}", getUserById,
PATH(Int32, userId))
2019-10-28 10:09:56 +08:00
{
2020-10-27 09:31:30 +08:00
return createDtoResponse(Status::CODE_200, m_userService.getUserById(userId));
2018-10-15 16:49:04 +08:00
}
2020-10-27 09:31:30 +08:00
```
2018-10-15 16:49:04 +08:00
2020-10-27 09:31:30 +08:00
### Access Databases And Keep Your Data Consistent
2019-10-28 10:25:45 +08:00
2020-10-27 09:31:30 +08:00
See [Oat++ ORM](https://oatpp.io/docs/components/orm/) for more details.
2019-10-28 10:25:45 +08:00
```cpp
2020-10-27 09:31:30 +08:00
QUERY(createUser,
"INSERT INTO users (username, email, role) VALUES (:username, :email, :role);",
PARAM(oatpp::String, username),
PARAM(oatpp::String, email),
PARAM(oatpp::Enum<UserRoles>::AsString, role))
2019-10-28 10:25:45 +08:00
```
2020-10-27 09:31:30 +08:00
## Frequently Asked Questions
2019-10-28 10:25:45 +08:00
2020-10-27 09:31:30 +08:00
### Q: "Oat++" name?
2019-10-28 10:25:45 +08:00
2020-10-27 09:31:30 +08:00
- "Oat" is something light, organic, and green. It can be easily cooked and consumed with no effort.
- "++" gives a hint that it is "something" for C++.
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
### Q: What is the main area of Oat++ application?
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
Oat++ is used for many different purposes, from building REST APIs that run on embedded devices to
building microservices and highly-loaded cloud applications.
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
But the majority of use cases appears to be in **IoT** and **Robotics**.
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
### Q: How portable is Oat++?
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
Theoretically, Oat++ can be **easily** ported everywhere where you have **threads** and **network stack**.
With an additional comparably small effort, it can be ported almost everywhere depending on how
much you strip it and what would be the final binary size.
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
See [supported platforms](https://oatpp.io/supported-platforms/) for additional info.
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
### Q: What is the size of a minimal Oat++ application?
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
About **1Mb**, depending on C/C++ std-lib and oatpp version.
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
### Q: Which Oat++ API to choose, Simple or Async?
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
Always choose **Simple API** wherever possible. Simple API is more developed and makes the code cleaner.
2019-10-28 10:15:26 +08:00
2020-10-27 09:31:30 +08:00
Async API is designed for small, specific tasks that run at high concurrency levels ex.:
- Serving file downloads to a large number of concurrent users (1K users and more).
- Streaming to a large number of clients (1K or more).
- Websocket Chat servers.
2020-05-17 09:34:17 +08:00
2020-10-27 09:31:30 +08:00
For all other purposes use simple API.
2020-05-17 09:34:17 +08:00
2020-10-27 09:31:30 +08:00
## Examples
2020-05-17 09:34:17 +08:00
2020-10-27 09:31:30 +08:00
### REST-API
2020-05-17 09:34:17 +08:00
2020-10-27 09:31:30 +08:00
- [REST Service](https://github.com/oatpp/example-crud) - A complete example of a "CRUD" service (UserService) built with Oat++. REST + Swagger-UI + SQLite.
- [REST Client](https://github.com/oatpp/example-api-client) - Example project of how-to use Retrofit-like client wrapper (ApiClient) and how it works.
2020-05-26 08:35:49 +08:00
2020-10-27 09:31:30 +08:00
### WebSocket
2020-05-31 16:11:53 +08:00
2020-10-27 09:31:30 +08:00
- [Can Chat](https://github.com/lganzzzo/canchat) - Feature-complete rooms-based chat for tens of thousands users. Client plus Server.
2019-06-25 08:52:17 +08:00
- [WebSocket](https://github.com/oatpp/example-websocket) - Collection of oatpp WebSocket examples.
2020-10-27 09:31:30 +08:00
- [YUV Websocket Stream](https://github.com/oatpp/example-yuv-websocket-stream) - Example project how-to create a YUV image stream from a V4L device (i.E. Webcam) using websockets.
### Databases
2020-05-26 08:35:49 +08:00
2020-10-27 09:31:30 +08:00
- [SQLite](https://github.com/oatpp/example-crud) - A complete example of a "CRUD" service. REST + Swagger-UI + SQLite.
- [PostgreSQL](https://github.com/oatpp/example-postgresql) - Example of a production-grade entity service storing information in PostgreSQL. With Swagger-UI and configuration profiles.
- [MongoDB](https://github.com/oatpp/example-mongodb) - Example project how to work with MongoDB using **oatpp-mongo** mondule. Project is a web-service with basic CRUD and Swagger-UI.
2020-06-16 21:07:00 +08:00
### IoT
- [Example-IoT-Hue](https://github.com/oatpp/example-iot-hue-ssdp) - Example project how-to create an Philips Hue compatible REST-API that is discovered and controllable by Hue compatible Smart-Home devices like Amazon Alexa or Google Echo.
2020-10-27 09:31:30 +08:00
### Streaming
2020-05-26 08:35:49 +08:00
2020-10-27 09:31:30 +08:00
- [HTTP Live Streaming Server](https://github.com/oatpp/example-hls-media-stream) - Example project on how to build an HLS-streaming server using Oat++ asynchronous API.
- [YUV Websocket Stream](https://github.com/oatpp/example-yuv-websocket-stream) - Example project how-to create a YUV image stream from a V4L device (i.E. Webcam) using websockets.
2020-05-26 08:35:49 +08:00
2020-10-27 09:31:30 +08:00
### TLS
2020-05-26 08:35:49 +08:00
2020-10-27 09:31:30 +08:00
- [TLS With Libressl](https://github.com/oatpp/example-libressl) - Example project how-to setup secure connection and serve via HTTPS.
2020-05-26 08:35:49 +08:00
2020-10-27 09:31:30 +08:00
### Microservices
2020-05-26 08:35:49 +08:00
2020-10-27 09:31:30 +08:00
- [Consul Integration](https://github.com/oatpp/example-consul) - Example project on how to use [oatpp::consul::Client](https://oatpp.io/api/latest/oatpp-consul/rest/Client/). Consul integration.
2020-05-26 08:35:49 +08:00
- [Microservices](https://github.com/oatpp/example-microservices) - Example project on how to build microservices with Oat++,
and example on how to consolidate those microservices using [monolithization](https://oatpp.io/docs/monolithization/) technique.
2020-06-16 21:07:00 +08:00
2020-10-27 09:31:30 +08:00
### Asynchronous API
2020-06-16 21:07:00 +08:00
2020-10-27 09:31:30 +08:00
- [Async Service](https://github.com/oatpp/example-async-api) - Example project on how to use asynchronous API to handle a large number of simultaneous connections.