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_resp_context structure is populated and passed to the rest_client_request() function. The same structure 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:

• CONFIG_REST_CLIENT_REQUEST_TIMEOUT

• CONFIG_REST_CLIENT_SCKT_SEND_TIMEOUT

• CONFIG_REST_CLIENT_SCKT_RECV_TIMEOUT

• CONFIG_REST_CLIENT_SCKT_TLS_SESSION_CACHE_IN_USE

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

enumerator REST_CLIENT_HTTP_STATUS_BAD_REQ

enumerator REST_CLIENT_HTTP_STATUS_UNAUTH

enumerator REST_CLIENT_HTTP_STATUS_FORBIDDEN

enumerator REST_CLIENT_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. Initialize to REST_CLIENT_TLS_DEFAULT_PEER_VERIFY and the default (TLS_PEER_VERIFY_REQUIRED) is used.

enum http_method http_method

Used HTTP method.

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.

int32_t timeout_ms

User-defined timeout value for receiving response data. 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.

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.