CMUTIL_RestClient Struct Reference

A JSON layer over CMUTIL_HttpClient. More...

Data Fields
CMUTIL_HttpClient	base
CMUTIL_Json *(*	Get )(CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri)
	Perform a GET request and parse the response as JSON.
CMUTIL_Json *(*	Post )(CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri, CMUTIL_Json *data)
	Perform a POST request with a JSON body.
CMBool(*	Put )(CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri, CMUTIL_Json *data)
	Perform a PUT request with a JSON body, discarding the response.
void(*	Delete )(CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri)
	Perform a DELETE request, discarding the response.
void(*	SetTimeout )(CMUTIL_RestClient *client, long timeout)
	Set the timeout applied to every REST request.
int(*	GetStatus )(const CMUTIL_RestClient *client)
	The HTTP status of the most recent request on this client.

Detailed Description

A JSON layer over CMUTIL_HttpClient.

A REST client serializes the request body from a CMUTIL_Json, parses the response body back into one, and adds the two JSON content negotiation headers when the caller did not supply them.

The first member is a complete CMUTIL_HttpClient, so a REST client can be used wherever one is expected:

  CMUTIL_RestClient *rest = CMUTIL_RestClientCreate("https://api.example.com");
  CMCall(&rest->base, SetVerify, CMTrue, CMTrue);
  CMUTIL_Json *user = CMCall(rest, Get, NULL, "/v1/users/42");
  ...
  CMUTIL_JsonDestroy(user);
  CMCall(&rest->base, Destroy);       // destroys the REST client too

All four REST methods report the HTTP status of the request they performed through GetStatus, which stays zero when the request never reached a response - a connection failure, a timeout or a malformed reply. The status belongs to the most recent request made through this client, so one client performs one request at a time.

Field Documentation

base

CMUTIL_HttpClient CMUTIL_RestClient::base

The underlying HTTP client. Use it for TLS settings, keep-alive, requests that are not JSON, and to destroy this object.

Get

CMUTIL_Json *(* CMUTIL_RestClient::Get) (CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri)

Perform a GET request and parse the response as JSON.

Parameters

client	This REST client object.
headers	Extra request headers, or NULL. The map is only read.
uri	Request URI, relative to the prefix given at creation.

Returns

The parsed response body, which the caller must destroy with CMUTIL_JsonDestroy. NULL when the request failed, the response carried no body, or the body was not JSON - check GetStatus to tell those apart.

Post

CMUTIL_Json *(* CMUTIL_RestClient::Post) (CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri, CMUTIL_Json *data)

Perform a POST request with a JSON body.

Parameters

client	This REST client object.
headers	Extra request headers, or NULL. The map is only read.
uri	Request URI, relative to the prefix given at creation.
data	The request body. Ownership stays with the caller.

Returns

The parsed response body, which the caller must destroy with CMUTIL_JsonDestroy, or NULL. See Get.

Put

CMBool(* CMUTIL_RestClient::Put) (CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri, CMUTIL_Json *data)

Perform a PUT request with a JSON body, discarding the response.

Parameters

client	This REST client object.
headers	Extra request headers, or NULL. The map is only read.
uri	Request URI, relative to the prefix given at creation.
data	The request body. Ownership stays with the caller.

Returns

CMTrue if the server answered with a 2xx status.

Delete

void(* CMUTIL_RestClient::Delete) (CMUTIL_RestClient *client, CMUTIL_Map *headers, const char *uri)

Perform a DELETE request, discarding the response.

Parameters

client	This REST client object.
headers	Extra request headers, or NULL. The map is only read.
uri	Request URI, relative to the prefix given at creation.

SetTimeout

void(* CMUTIL_RestClient::SetTimeout) (CMUTIL_RestClient *client, long timeout)

Set the timeout applied to every REST request.

The REST methods take no timeout of their own; this is it. A new client starts at CMUTIL_REST_DEFAULT_TIMEOUT.

Parameters

client	This REST client object.
timeout	Timeout in milliseconds.

GetStatus

int(* CMUTIL_RestClient::GetStatus) (const CMUTIL_RestClient *client)

The HTTP status of the most recent request on this client.

Parameters

client

This REST client object.

Returns

The status code, or zero if the request never got a response.

---

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

• /home/runner/work/libcmutils/libcmutils/src/libcmutils.h