Skip to content

Learning Oat++ HTTP Client: A Quick Setup Guide

Introduction

For the past few weeks, I've been learning the Oat++ HTTP client library to develop a library for my company. After struggling for two days to get it working, I finally succeeded and wanted to share my experience.

The Challenge

I initially tried to follow the official example from https://github.com/oatpp/example-api-client, but it wouldn't run due to linking issues with the oatpp-curl configuration. Since I only wanted to observe the Oat++ client call stack for documentation purposes, I needed a quick solution.

The Solution

I switched to using Ubuntu 22.04 as my host environment and after several hours of trial and error, I managed to create a working setup. I've packaged this into a personal reference repository that demonstrates both synchronous and asynchronous HTTP client operations.

The complete source code is available on GitHub at https://github.com/henryle-sys/oatpp-client-demo, and for convenience, I've also created a Docker image available at https://hub.docker.com/r/hbkswe/oatpp-client-demo that contains the complete development environment.

Quick Setup

Getting the Source Code

First, clone the repository:

git clone https://github.com/henryle-sys/oatpp-client-demo.git
cd oatpp-client-demo

The easiest way to get started is using the pre-built Docker image as your development environment:

docker run --shm-size=1g --privileged=true \
    -v $(pwd):/sources \
    -w /sources -it \
    --network host \
    --name ${USER}_rest_client_api_dev \
    hbkswe/oatpp-client-demo

This will: - Mount your current directory to /sources in the container - Set the working directory to /sources - Use host networking for HTTP requests - Provide a complete development environment with all dependencies

Once inside the container, you'll need to build the code using the CMake configuration below.

Option 2: Local Build

If you prefer to build locally (without Docker), follow these steps:

CMake Configuration

Add this to your CMakeLists.txt file, replacing path_to_your_source with your actual source path:

if (BUILD_OATPP_DEMO)
    SET(OATPP_CLIENT_DEMO_SRC path_to_your_source)

    LIST(APPEND OATPP_CLIENT_DEMO_SOURCE ${OATPP_CLIENT_DEMO_SRC}/src/main.cpp)
    LIST(APPEND OATPP_CLIENT_DEMO_SOURCE ${OATPP_CLIENT_DEMO_SRC}/src/AsyncExample.cpp)
    ADD_EXECUTABLE(demo_oatpp ${OATPP_CLIENT_DEMO_SOURCE})

    LIST(APPEND OATPP_CLIENT_DEMO_HEADER ${OATPP_CLIENT_DEMO_SRC}/src})
    TARGET_INCLUDE_DIRECTORIES(demo_oatpp PRIVATE ${OATPP_CLIENT_DEMO_HEADER})

    LIST(APPEND OATPP_CLIENT_DEMO_LINKAGE oatpp::oatpp)
    LIST(APPEND OATPP_CLIENT_DEMO_LINKAGE oatpp::oatpp-test)
    LIST(APPEND OATPP_CLIENT_DEMO_LINKAGE oatpp::oatpp-curl)
    TARGET_LINK_LIBRARIES(demo_oatpp PRIVATE ${OATPP_CLIENT_DEMO_LINKAGE})
endif ()

Building the Project

cmake -S . -B ./build
cmake --build ./build -j"$(nproc)"

Running the Demo

To observe HTTP method calls to httpbin.org:

./build/demo_oatpp

Building Inside Docker Container

If you're using the Docker environment (Option 1), once inside the container, you can build and run the project using the same commands:

# Inside the Docker container
cmake -S . -B ./build
cmake --build ./build -j"$(nproc)"
./build/demo_oatpp

Sample Output

The demo will show various HTTP requests including GET, POST, and async operations:

D |2025-08-23 13:28:47 1755926927325367| App:Using Oat++ native HttpRequestExecutor.
D |2025-08-23 13:28:49 1755926929199472| SimpleExample:[doGet] data='{
  "args": {},
  "headers": {
    "Content-Length": "0",
    "Host": "httpbin.org",
    "X-Amzn-Trace-Id": "Root=1-68a9518f-2575b1c36aeaad90653c174a"
  },
  "origin": "49.216.163.161",
  "url": "http://httpbin.org/get"
}'
D |2025-08-23 13:28:49 1755926929751898| SimpleExample:[doPost] data='{
  "args": {},
  "data": "Some data passed to POST",
  "files": {},
  "form": {},
  "headers": {
    "Content-Length": "24",
    "Host": "httpbin.org",
    "X-Amzn-Trace-Id": "Root=1-68a95190-7611adb54b72cd2a070e15d0"
  },
  "json": null,
  "origin": "49.216.163.161",
  "url": "http://httpbin.org/post"
}'

The demo includes: - Simple GET and POST requests - Requests with path parameters - JSON DTO serialization - Asynchronous operations - Multiple concurrent async requests

Key Features Demonstrated

  1. Synchronous HTTP Client: Basic GET/POST operations
  2. Asynchronous HTTP Client: Non-blocking requests with callbacks
  3. DTO Serialization: JSON object mapping
  4. Request Executors: Both native Oat++ and curl-based executors
  5. Error Handling: Proper request/response management

Environment Information

The demo also shows Oat++ environment statistics:

Environment:
objectsCount = 0
objectsCreated = 102

This helps verify that there are no memory leaks in the application.

Conclusion

This setup provides a clean, working example of Oat++ HTTP client usage that can serve as a reference for future development. The demo covers the most common use cases and demonstrates both synchronous and asynchronous patterns.

This repository serves as a personal reference for Oat++ HTTP client development and can be used as a starting point for similar projects.

Share this page:

LinkedIn Twitter Facebook

Comments