REST client

The REST client library provides means for performing REST requests.

Overview

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_context structure is populated and passed to the rest_client_request() function together with the rest_client_resp_context structure, which will contain the response data.

Configuration

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:

Limitations

  • 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.

API documentation

Header file: include/net/rest_client.h
Source files: subsys/net/lib/rest_client
group rest_client

REST client.

Provide REST client functionality.

Defines

REST_CLIENT_SEC_TAG_NO_SEC

TLS is not used.

REST_CLIENT_TLS_DEFAULT_PEER_VERIFY

Use the default TLS peer verification; TLS_PEER_VERIFY_REQUIRED.

REST_CLIENT_SCKT_CONNECT

REST client opens a socket connection.

Enums

enum rest_client_http_status

Common HTTP status codes.

Values:

enumerator REST_CLIENT_HTTP_STATUS_OK

HTTP status: OK.

enumerator REST_CLIENT_HTTP_STATUS_BAD_REQ

HTTP status: Bad request.

enumerator REST_CLIENT_HTTP_STATUS_UNAUTH

HTTP status: Unauthorized.

enumerator REST_CLIENT_HTTP_STATUS_FORBIDDEN

HTTP status: Forbidden.

enumerator REST_CLIENT_HTTP_STATUS_NOT_FOUND

HTTP status: Not found.

Functions

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.

Parameters:

  • 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.

void rest_client_request_defaults_set(struct rest_client_req_context *req_ctx)

Sets the default values into a given request context.

Intended to be used before calling rest_client_request().

Parameters:

  • req_ctx – [inout] Request context for communicating with REST client API.

struct rest_client_req_context
#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.

Public Members

int connect_socket

Socket identifier for the connection. When using the default value, the library will open a new socket connection. Default: REST_CLIENT_SCKT_CONNECT.

bool keep_alive

Defines whether the connection should remain after API call. Default: false.

int sec_tag

Security tag. Default: REST_CLIENT_SEC_TAG_NO_SEC.

int tls_peer_verify

Indicates the preference for peer verification. Default: REST_CLIENT_TLS_DEFAULT_PEER_VERIFY.

enum http_method http_method

Used HTTP method. Default: HTTP_GET.

const char *host

Hostname or IP address to be used in the request.

uint16_t port

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.

size_t body_len

Payload/body length

int32_t timeout_ms

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 .

char *resp_buff

User-allocated buffer for receiving API response.

size_t resp_buff_len

User-defined size of resp_buff.

struct rest_client_resp_context
#include <rest_client.h>

REST client response context.

When rest_client_request returns, response-related data can be read from this structure.

Public Members

size_t total_response_len

Length of HTTP headers + response body/content data.

size_t response_len

Length of response body/content data.

char *response

Start of response data (the body/content) in resp_buff.

uint16_t http_status_code

Numeric HTTP status code.

char http_status_code_str[HTTP_STATUS_STR_SIZE]

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.

int used_socket_id

Used socket identifier. Use this for keepalive connections as connect_socket for upcoming requests.

int used_socket_is_alive

True if used_socket_id was kept alive and was not closed after the REST request.