The REST client library provides means for performing REST requests.
This library creates a socket with TLS when requested.
It uses Zephyr’s HTTP client library to send HTTP requests and receive HTTP responses.
When using this library, the
rest_client_req_resp_context structure is populated and passed to the
The same structure will contain the response data.
To use the REST client library, enable the
CONFIG_REST_CLIENT Kconfig option.
You can configure the following options to adjust the behavior of the library:
Executing REST request is a blocking operation. The calling thread is blocked until the request has completed.
REST client only works in the default PDP context.
REST client do not allow selection of IPV4 or IPV6 but it works on what DNS returns for name query.
- group rest_client
Provide REST client functionality.
TLS is not used.
Use the default TLS peer verification; TLS_PEER_VERIFY_REQUIRED.
REST client opens a socket connection.
int rest_client_request(struct rest_client_req_context *req_ctx, struct rest_client_resp_context *resp_ctx)
REST client request.
This function will block the calling thread until the request completes.
req_ctx – [in] Request context containing input parameters to REST request
resp_ctx – [out] Response context for returning the response data.
- Return values
0, if – the REST response was received successfully. If response_len > 0, there is also body/content data in a response. http_status_code contains the actual HTTP status code. Otherwise, a (negative) error code is returned.
- #include <rest_client.h>
REST client request context.
Input parameters for using the REST client API should be filled into this structure before calling rest_client_request.
Socket identifier for the connection. When using the default value, the library will open a new socket connection. Default: REST_CLIENT_SCKT_CONNECT.
Defines whether the connection should remain after API call. Default: false.
Security tag. Default: REST_CLIENT_SEC_TAG_NO_SEC.
Indicates the preference for peer verification. Initialize to REST_CLIENT_TLS_DEFAULT_PEER_VERIFY and the default (TLS_PEER_VERIFY_REQUIRED) is used.
const char *host
Hostname or IP address to be used in the request.
Port number to be used in the request.
const char *url
The URL for this request, for example: /index.html
const char **header_fields
The HTTP header fields. Similar to the Zephyr HTTP client. This is a NULL-terminated list of header fields. May be NULL.
const char *body
Payload/body, may be NULL.
User-defined timeout value for REST request. The timeout is set individually for socket connection creation and data transfer meaning REST request can take longer than this given timeout. To disable, set the timeout duration to SYS_FOREVER_MS. A value of zero will result in an immediate timeout. Default: CONFIG_REST_CLIENT_REST_REQUEST_TIMEOUT.
User-allocated buffer for receiving API response.
User-defined size of resp_buff.
- int connect_socket
- #include <rest_client.h>
REST client response context.
When rest_client_request returns, response-related data can be read from this structure.
Length of HTTP headers + response body/content data.
Length of response body/content data.
Start of response data (the body/content) in resp_buff.
Numeric HTTP status code.
HTTP status code as a textual description, i.e. the reason-phrase element. https://tools.ietf.org/html/rfc7230#section-3.1.2 Copied here from http_status of http_response.
Used socket identifier. Use this for keepalive connections as connect_socket for upcoming requests.
True if used_socket_id was kept alive and was not closed after the REST request.
- size_t total_response_len