{"id":19492798,"url":"https://github.com/oatpp/example-api-client","last_synced_at":"2025-10-28T03:13:04.290Z","repository":{"id":98397792,"uuid":"168231478","full_name":"oatpp/example-api-client","owner":"oatpp","description":"Example project how-to use oatpp ApiClient and how it works","archived":false,"fork":false,"pushed_at":"2024-04-22T21:24:52.000Z","size":26,"stargazers_count":25,"open_issues_count":6,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-29T22:52:05.871Z","etag":null,"topics":["api-client","cpp","curl","oatpp","rest-client"],"latest_commit_sha":null,"homepage":"https://oatpp.io/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oatpp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-29T21:25:04.000Z","updated_at":"2024-09-08T05:24:39.000Z","dependencies_parsed_at":"2024-11-07T00:35:39.099Z","dependency_job_id":null,"html_url":"https://github.com/oatpp/example-api-client","commit_stats":{"total_commits":32,"total_committers":1,"mean_commits":32.0,"dds":0.0,"last_synced_commit":"9df55e1da0788f6513b298da1186a2151d55f8bb"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Fexample-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Fexample-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Fexample-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oatpp%2Fexample-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oatpp","download_url":"https://codeload.github.com/oatpp/example-api-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224015660,"owners_count":17241535,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","cpp","curl","oatpp","rest-client"],"created_at":"2024-11-10T21:23:04.205Z","updated_at":"2025-10-28T03:13:04.236Z","avatar_url":"https://github.com/oatpp.png","language":"C++","readme":"# ApiClient Example [![Build Status](https://dev.azure.com/lganzzzo/lganzzzo/_apis/build/status/oatpp.example-api-client?branchName=master)](https://dev.azure.com/lganzzzo/lganzzzo/_build?definitionId=14\u0026branchName=master)\n\nExample project how-to use oatpp [ApiClient](https://oatpp.io/docs/components/api-client/) and how it works.\n\nSee more:\n\n- [Oat++ Website](https://oatpp.io/)\n- [Oat++ Github Repository](https://github.com/oatpp/oatpp)\n- [Get Started](https://oatpp.io/docs/start)\n\n## About ApiClient\n\noatpp `ApiClient` is a mechanism which enables you to generate Web Api Clients in declarative manner.\nUnder the hood it uses provided `RequestExecutor` to perform http requests. Thus you are abstracted from the low-level http-client library implementation and can substitute any other http-client library at any time with zero code changes.  \n*Roughly you may treat oatpp `ApiClient` as Java Retrofit for C++.*\n\nIn this example you can configure to use such RequestExecutors:\n\n- [oatpp-curl](https://github.com/oatpp/oatpp-curl) - RequestExecutor for oatpp's ApiClient based on libcurl.\n- `oatpp::web::client::HttpRequestExecutor` - oatpp out-of-the-box provided RequestExecutor\n\nPlease note: it is recommended to use native out-of-the-box `oatpp::web::client::HttpRequestExecutor`. It is better integrated \nwith oatpp and supports additional features like connection pools, retries, streaming of large data, and custom transport substitution.\n\n## Example overview\n\nIn this example you will find: \n- ```ApiClient``` built for http://httpbin.org/ web service.\n- Simple (Synchronous) API calls example.\n- Async API calls example processed with ```oatpp::async::Processor``` and ```oatpp::async::Coroutine```.\n\n### Project layout\n\n```\n|- CMakeLists.txt                          // projects CMakeLists.txt\n|- src/\n|   |- DemoApiClient.hpp                   // ApiClient built for http://httpbin.org/ web service\n|   |- DemoApiModels.hpp                   // DTOs objects for DemoApiClient\n|   |- SimpleExample.hpp                   // Simple (Synchronous) API calls example\n|   |- AsyncExample.hpp                    // Async API calls example\n|   |- App.cpp                             // main is here\n|   \n|- test/                                   // test folder\n|- utility/install-oatpp-modules.sh        // utility script to install required oatpp-modules.\n```\n---\n\n### Build and Run\n\n#### Using CMake\n\n**Requires** \n\n- Curl installed. You may refer to this sh script - how to install curl - \n[install-curl.sh](https://github.com/oatpp/oatpp-curl/blob/master/utility/install-deps/install-curl.sh).  \nOr try something like ```$ apk add curl-dev```\n\n- `oatpp` and `oatpp-curl` modules installed. You may run `utility/install-oatpp-modules.sh` \nscript to install required oatpp modules.\n\n```\n$ mkdir build \u0026\u0026 cd build\n$ cmake ..\n$ make \n$ ./example-api-client-exe      # - run application.\n\n```\n\n#### In Docker\n\n```\n$ docker build -t example-api-client .\n$ docker run -t example-api-client\n```\n---\n\n### ApiClient declaration overview\n\nUse ```API_CALL``` for simple (synchronous) calls.  \nUse ```API_CALL_ASYNC``` for non-blocking Async calls.\n\n```c++\nclass DemoApiClient : public oatpp::web::client::ApiClient {\n#include OATPP_CODEGEN_BEGIN(ApiClient)\n  \n  API_CLIENT_INIT(DemoApiClient)\n  \n  ...\n  \n  API_CALL(\"GET\", \"get\", doGet)\n  API_CALL(\"POST\", \"post\", doPost, BODY_STRING(String, body))\n  \n  ...\n  \n  API_CALL_ASYNC(\"GET\", \"get\", doGetAsync)\n  API_CALL_ASYNC(\"POST\", \"post\", doPostAsync, BODY_STRING(String, body))\n\n  ...\n  \n#include OATPP_CODEGEN_END(ApiClient)\n};\n```\n\n### Example calls overview\n\n#### SimpleExample.hpp\n\n```c++\n{\n  auto data = client-\u003edoGet()-\u003ereadBodyToString();\n  OATPP_LOGD(TAG, \"[doGet] data='%s'\", data-\u003ec_str());\n}\n\n{\n  auto data = client-\u003edoPost(\"Some data passed to POST\")-\u003ereadBodyToString();\n  OATPP_LOGD(TAG, \"[doPost] data='%s'\", data-\u003ec_str());\n}\n```\n\n#### AsyncExample.hpp\n\n```c++\nclass SendCoroutine : public oatpp::async::Coroutine\u003cSendCoroutine\u003e {\nprivate:\n  std::shared_ptr\u003cDemoApiClient\u003e m_client;\npublic:\n\n  SendCoroutine(const std::shared_ptr\u003cDemoApiClient\u003e client) : m_client(client) {}\n\n  Action act() override {\n    return m_client-\u003edoPostAsync(\"\u003cPOST-DATA-HERE\u003e\").callbackTo(\u0026SendDtoCoroutine::onResponse);\n  }\n\n  Action onResponse(const std::shared_ptr\u003cResponse\u003e\u0026 response) {\n    return response-\u003ereadBodyToStringAsync().callbackTo(\u0026SendDtoCoroutine::onBody);\n  }\n\n  Action onBody(const oatpp::String\u0026 body) {\n    OATPP_LOGD(TAG, \"[SendCoroutine. doPostAsync] data='%s'\", body-\u003ec_str());\n    return finish();\n  }\n\n};\n```\n\n### Request executor configuration\n\nIn ```App.cpp``` method ```run```.\nTry to substitute different ```RequestExecutors``` by switching from Curl to oatpp built-in request executor.\n\n```c++\n\nvoid run(){\n  \n  /* Create ObjectMapper for serialization of DTOs  */\n  auto objectMapper = oatpp::parser::json::mapping::ObjectMapper::createShared();\n  \n  /* Create RequestExecutor which will execute ApiClient's requests */\n  //auto requestExecutor = createOatppExecutor();  // \u003c-- Uncomment this\n  auto requestExecutor = createCurlExecutor();     // \u003c-- Comment this\n  \n  /* DemoApiClient uses DemoRequestExecutor and json::mapping::ObjectMapper */\n  /* ObjectMapper passed here is used for serialization of outgoing DTOs */\n  auto client = DemoApiClient::createShared(requestExecutor, objectMapper);\n  \n  SimpleExample::runExample(client);\n  AsyncExample::runExample(client);\n  \n}\n\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foatpp%2Fexample-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foatpp%2Fexample-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foatpp%2Fexample-api-client/lists"}