You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
147 lines
4.6 KiB
Markdown
147 lines
4.6 KiB
Markdown
# webcc
|
|
|
|
A lightweight C++ REST and SOAP client and server library based on *Boost.Asio*.
|
|
|
|
Please turn to our [Wiki](https://github.com/sprinfall/webcc/wiki) for more tutorials and guides.
|
|
|
|
## Quick Start
|
|
|
|
### REST Server
|
|
|
|
Suppose you want to create a book server, and provide the following operations with RESTful API:
|
|
|
|
- Query books based on some criterias.
|
|
- Add a new book.
|
|
- Get the detailed information of a book.
|
|
- Update the information of a book.
|
|
- Delete a book.
|
|
|
|
The first two operations can be implemented by deriving from `webcc::RestListService`:
|
|
|
|
```cpp
|
|
class BookListService : public webcc::RestListService {
|
|
protected:
|
|
// Query books based on some criterias.
|
|
// GET /books?<query>
|
|
bool Get(const webcc::UrlQuery& query,
|
|
std::string* response_content) override;
|
|
|
|
// Add a new book.
|
|
// POST /books
|
|
// The new book's data is attached as request content in JSON format.
|
|
bool Post(const std::string& request_content,
|
|
std::string* response_content) override;
|
|
};
|
|
```
|
|
|
|
The others, derive from `webcc::RestDetailService`:
|
|
|
|
```cpp
|
|
// The URL is like '/book/{BookID}', and the 'url_sub_matches' parameter
|
|
// contains the matched book ID.
|
|
class BookDetailService : public webcc::RestDetailService {
|
|
protected:
|
|
// Get the detailed information of a book.
|
|
bool Get(const std::vector<std::string>& url_sub_matches,
|
|
const webcc::UrlQuery& query,
|
|
std::string* response_content) override;
|
|
|
|
// Update the information of a book.
|
|
bool Put(const std::vector<std::string>& url_sub_matches,
|
|
const std::string& request_content,
|
|
std::string* response_content) override;
|
|
|
|
// Delete a book.
|
|
bool Delete(const std::vector<std::string>& url_sub_matches) override;
|
|
};
|
|
```
|
|
|
|
As you can see, all you have to do is to override the proper virtual functions which are named after HTTP methods.
|
|
|
|
The detailed implementation is out of the scope of this document, but here is an example:
|
|
|
|
```cpp
|
|
bool BookDetailService::Get(const std::vector<std::string>& url_sub_matches,
|
|
const webcc::UrlQuery& query,
|
|
std::string* response_content) {
|
|
if (url_sub_matches.size() != 1) {
|
|
return false;
|
|
}
|
|
const std::string& book_id = url_sub_matches[0];
|
|
|
|
// Get the book by ID from database.
|
|
// Convert the book details to JSON string.
|
|
// Assign JSON string to response_content.
|
|
}
|
|
```
|
|
|
|
Last step, bind the services and run the server:
|
|
|
|
```cpp
|
|
webcc::RestServer server(8080, 2);
|
|
|
|
server.Bind(std::make_shared<BookListService>(), "/books", false);
|
|
server.Bind(std::make_shared<BookDetailService>(), "/book/(\\d+)", true);
|
|
|
|
server.Run();
|
|
```
|
|
|
|
**Please see the `example/rest` folder for the complete examples (including the client).**
|
|
|
|
## Build Instructions
|
|
|
|
A lot of C++11 features are used, e.g., `std::move`. But C++14 is not required.
|
|
(It means that you can still build `webcc` using VS2013 on Windows.)
|
|
|
|
[CMake 3.1.0+](https://cmake.org/) is required as the build system. But if you don't use CMake, you can just copy the `src/webcc` folder to your own project then manage it by yourself.
|
|
|
|
[C++ Boost](https://www.boost.org/) should be 1.66+ because Asio made some broken changes to the API in 1.66.
|
|
|
|
### Build Options
|
|
|
|
The following CMake options determine how you build the projects. They are quite self-explanatory.
|
|
|
|
```cmake
|
|
option(WEBCC_ENABLE_LOG "Enable logging?" ON)
|
|
option(WEBCC_ENABLE_SOAP "Enable SOAP support (need pugixml)?" ON)
|
|
option(WEBCC_BUILD_UNITTEST "Build unit test?" ON)
|
|
option(WEBCC_BUILD_EXAMPLE "Build examples?" ON)
|
|
|
|
set(WEBCC_LOG_LEVEL "VERB" CACHE STRING "Log level (VERB, INFO, WARN, ERRO or FATA)")
|
|
```
|
|
|
|
Options `WEBCC_ENABLE_LOG` and `WEBCC_LOG_LEVEL` together define how logging behaves. See [Wiki/Logging](https://github.com/sprinfall/webcc/wiki/Logging) for more details.
|
|
|
|
If `WEBCC_ENABLE_SOAP` is `ON`, **pugixml** (already included) is used to parse and compose XML strings.
|
|
|
|
### Build On Linux
|
|
|
|
Create a build folder under the root (or any other) directory, and `cd` to it:
|
|
```bash
|
|
mkdir build
|
|
cd build
|
|
```
|
|
Generate Makefiles with the following command:
|
|
```bash
|
|
cmake -G"Unix Makefiles" \
|
|
-DCMAKE_INSTALL_PREFIX=~ \
|
|
-DWEBCC_ENABLE_LOG=ON \
|
|
-DWEBCC_LOG_LEVEL=VERB \
|
|
-DWEBCC_ENABLE_SOAP=ON \
|
|
-DWEBCC_BUILD_UNITTEST=OFF \
|
|
-DWEBCC_BUILD_EXAMPLE=ON \
|
|
..
|
|
```
|
|
Feel free to change the build options (`ON` or `OFF`).
|
|
CMake variable `CMAKE_INSTALL_PREFIX` defines where to install the output library and header files. The default is `/usr/local`.
|
|
|
|
If everything is OK, then you can build with `make`:
|
|
```bash
|
|
$ make -j4 # or -j8, depending on how many CPU cores you have.
|
|
```
|
|
|
|
Then install:
|
|
```bash
|
|
$ make install
|
|
```
|