cpp_restapi::IConnection Struct Reference

Interface representing connection with rest api server. More...

#include <iconnection.hpp>

Inheritance diagram for cpp_restapi::IConnection:

Public Types
using	EventCallback = std::function<void(const SseEvent&)>
using	FetchCallback = std::function<void(Response)>
using	BodyCallback = std::function<void(std::string)>
using	ErrorCallback = std::function<void(HttpError)>

Public Member Functions
virtual	~IConnection ()=default
virtual const std::string &	url () const =0
	return API url
virtual std::expected< std::string, HttpError >	fetch (const std::string &request)=0
	Perform a single HTTP request.
virtual std::expected< std::string, HttpError >	fetch (const std::string &request, IPaginationStrategy &strategy)=0
	Perform requests with automatic pagination.
virtual std::expected< Response, HttpError >	fetchResponse (const std::string &url)=0
	Perform a single HTTP request returning the full response.
virtual CancellationToken	fetch (const std::string &request, FetchCallback onSuccess, ErrorCallback onError={})=0
	Perform an HTTP GET request asynchronously.
virtual CancellationToken	fetch (const std::string &request, IPaginationStrategy &strategy, BodyCallback onSuccess, ErrorCallback onError={})=0
	Perform paginated requests asynchronously.
virtual std::unique_ptr< ISseConnection >	subscribe (const std::string &request, EventCallback callback)=0
	Subscribe to an SSE endpoint.
virtual std::string	get (const std::string &request)=0
	perform a request to api

Detailed Description

Interface representing connection with rest api server.

Member Typedef Documentation

BodyCallback

using cpp_restapi::IConnection::BodyCallback = std::function<void(std::string)>

ErrorCallback

using cpp_restapi::IConnection::ErrorCallback = std::function<void(HttpError)>

EventCallback

using cpp_restapi::IConnection::EventCallback = std::function<void(const SseEvent&)>

FetchCallback

using cpp_restapi::IConnection::FetchCallback = std::function<void(Response)>

Constructor & Destructor Documentation

~IConnection()

virtual cpp_restapi::IConnection::~IConnection ( )

virtualdefault

Member Function Documentation

fetch() [1/4]

virtual std::expected< std::string, HttpError > cpp_restapi::IConnection::fetch ( const std::string & request )

pure virtual

Perform a single HTTP request.

Parameters

request

relative API path (e.g. "api/v1/disks")

Returns

response body on success, or an HttpError describing the failure

Returns std::unexpected(HttpError) when:

• The server returns a 4xx or 5xx status code
• A network-level failure occurs (statusCode == 0 in the error)

Implemented in cpp_restapi::BaseConnection, cpp_restapi::QtBackend::Connection, and cpp_restapi::ThreadedConnection.

fetch() [2/4]

virtual CancellationToken cpp_restapi::IConnection::fetch ( const std::string & request, FetchCallback onSuccess, ErrorCallback onError = {} )

pure virtual

Perform an HTTP GET request asynchronously.

Non-blocking. onSuccess is called with the full response when the request completes successfully; onError is called with an HttpError if the request fails. The callbacks may be invoked from a background thread (non-Qt backends) or from the Qt event-loop thread (Qt backend) — callers must handle thread-safety accordingly.

Parameters

request	relative API path (e.g. "users/octocat")
onSuccess	called with Response{body, headers, statusCode} on success
onError	called with an HttpError on failure (optional)

Returns

cancellation token; store it and set to true to suppress callbacks

Implemented in cpp_restapi::BaseConnection, cpp_restapi::QtBackend::Connection, and cpp_restapi::ThreadedConnection.

fetch() [3/4]

virtual std::expected< std::string, HttpError > cpp_restapi::IConnection::fetch ( const std::string & request, IPaginationStrategy & strategy )

pure virtual

Perform requests with automatic pagination.

Parameters

request	relative API path
strategy	pagination strategy defining how to discover next page and merge results

Returns

merged response body from all pages on success, or an HttpError on first failure

Implemented in cpp_restapi::BaseConnection, cpp_restapi::QtBackend::Connection, and cpp_restapi::ThreadedConnection.

fetch() [4/4]

virtual CancellationToken cpp_restapi::IConnection::fetch ( const std::string & request, IPaginationStrategy & strategy, BodyCallback onSuccess, ErrorCallback onError = {} )

pure virtual

Perform paginated requests asynchronously.

Non-blocking. Pages are fetched sequentially; once all pages have been collected the merged result is delivered via onSuccess. On any page failure onError is called and fetching stops.

Parameters

request	relative API path (e.g. "repos/owner/name/issues")
strategy	pagination strategy (next-page discovery and merge)
onSuccess	called with the merged body string on success
onError	called with an HttpError on failure (optional)

Returns

cancellation token

Implemented in cpp_restapi::BaseConnection, cpp_restapi::QtBackend::Connection, and cpp_restapi::ThreadedConnection.

fetchResponse()

virtual std::expected< Response, HttpError > cpp_restapi::IConnection::fetchResponse ( const std::string & url )

pure virtual

Perform a single HTTP request returning the full response.

Parameters

url	full URL to fetch

Returns

full Response (body, headers, statusCode) on success, or an HttpError on failure

Implemented in cpp_restapi::BaseConnection.

get()

virtual std::string cpp_restapi::IConnection::get ( const std::string & request )

pure virtual

perform a request to api

Parameters

request

api request. For example "users/SomeUserName/repos"

Returns

api response in json format

Deprecated

Use fetch() for single requests or fetch() with IPaginationStrategy for paginated requests. This method has hardcoded GitHub-specific pagination logic.

Implemented in cpp_restapi::BaseConnection.

subscribe()

virtual std::unique_ptr< ISseConnection > cpp_restapi::IConnection::subscribe ( const std::string & request, EventCallback callback )

pure virtual

Subscribe to an SSE endpoint.

Parameters

request	API endpoint path (e.g. "events" or "api/v1/events")
callback	function called for each received SSE event

Returns

SSE connection handle; use its close() method to stop

Implemented in cpp_restapi::CppHttplibBackend::Connection, cpp_restapi::CurlBackend::Connection, and cpp_restapi::QtBackend::Connection.

url()

virtual const std::string & cpp_restapi::IConnection::url ( ) const

pure virtual

return API url

Implemented in cpp_restapi::BaseConnection.

---

The documentation for this struct was generated from the following file:

• include/cpp_restapi/iconnection.hpp