nRF Cloud REST

The nRF Cloud REST library enables applications to use nRF Cloud’s REST-based device API. This library is an enhancement to the nRF Cloud library.

Usage

This library exposes a number of functions that provide access to nRF Cloud REST API endpoints.

When called, these functions initiate an HTTP request to the nRF Cloud REST backend. Various nRF Cloud REST API endpoints are provided for tasks such as:

  • Updating a device’s shadow.

  • Sending and receiving device messages.

  • Interacting with location services.

All of these functions operate on a nrf_cloud_rest_context structure that you must initialize and provide with your desired parameters. When each function returns, the context contains the status of the API call.

Authentication

Each HTTP/REST request must include a valid JSON Web Token (JWT) that serves as a proof of identity. Usually, these tokens are generated based on the device credentials, and must be passed to the auth parameter of the nrf_cloud_rest_context structure. To generate a token, call the nrf_cloud_jwt_generate() function, or use the Modem JWT library. Alternatively, if you have enabled the NRF_CLOUD_REST_AUTOGEN_JWT option (along with its dependencies), the nRF Cloud REST library generates a JWT automatically if one is not provided.

Socket management and reuse

The socket used for each HTTP request is determined by the connect_socket parameter of the nrf_cloud_rest_context structure. If a valid socket file descriptor is passed, this socket is used. If -1 is passed, a socket will be created automatically.

The selected socket can be reused depending on the passed-in value of the keep_alive property of the nrf_cloud_rest_context structure:

  • If you set keep_alive to false, then the selected socket is closed after each request, and the connect_socket property is reset to -1.

  • If you set keep_alive to true, the socket remains open and connect_socket remains unaltered, meaning the socket is reused on the next API call.

However, if you set keep_alive to true, make sure that the socket has not been closed externally (for example, due to inactivity) before sending each request. Otherwise, the request will be dropped.

There are two ways a timed out socket can manifest:

  • The socket may be closed immediately on timeout, causing -ENOTCONN to be returned by the next REST request function call, without reaching nRF Cloud.

  • The socket may be left open, allowing the next REST request to reach nRF Cloud, but the request is ignored and the socket is closed gracefully (FIN,ACK) with null HTTP response. In this case, the called request function returns -ESHUTDOWN.

See Request failure for more details.

Request success

If the API call is successful, the context also contains the response data and length. Some functions also have an optional result parameter. If this parameter is provided, the response data is parsed into result.

A number of functions automatically handle response data themselves:

Request failure

If an API call is unsuccessful, the called request function may return a variety of outputs:

  • If the error occurred at the socket level, the exact socket errno is returned. For instance, -ENOTCONN if the socket was closed, or was never opened before the request was made.

  • If the remote endpoint closes the connection gracefully without giving a response (a null HTTP response), -ESHUTDOWN is returned.

  • If the remote endpoint responds with an unexpected HTTP status code (indicating request rejection), -EBADMSG is returned. Possible causes include, but are not limited to: bad endpoint, invalid request data, invalid JWT.

  • If the response body is empty and the request expects response data, -ENODATA is returned.

  • If a heap allocation fails, -ENOMEM is returned.

  • Request formatting errors return -ETXTBSY

Some functions may have additional return values. These are documented on the function itself.

Configuration

Configure the CONFIG_NRF_CLOUD_REST option to enable or disable the use of this library.

Additionally, configure the following options for the needs of your application:

API documentation

Header file: include/net/nrf_cloud_rest.h
Source files: subsys/net/lib/nrf_cloud/src/
group nrf_cloud_rest

Defines

NRF_CLOUD_REST_TIMEOUT_MINIMUM
NRF_CLOUD_REST_TIMEOUT_NONE

Enums

enum nrf_cloud_http_status

HTTP status codes returned from nRF Cloud.

Values:

enumerator NRF_CLOUD_HTTP_STATUS_UNHANDLED
enumerator NRF_CLOUD_HTTP_STATUS_NONE
enumerator NRF_CLOUD_HTTP_STATUS_OK
enumerator NRF_CLOUD_HTTP_STATUS_ACCEPTED
enumerator NRF_CLOUD_HTTP_STATUS_PARTIAL
enumerator NRF_CLOUD_HTTP_STATUS__ERROR_BEGIN
enumerator NRF_CLOUD_HTTP_STATUS_BAD_REQ
enumerator NRF_CLOUD_HTTP_STATUS_UNAUTH
enumerator NRF_CLOUD_HTTP_STATUS_FORBIDDEN
enumerator NRF_CLOUD_HTTP_STATUS_NOT_FOUND
enumerator NRF_CLOUD_HTTP_STATUS_BAD_RANGE
enumerator NRF_CLOUD_HTTP_STATUS_UNPROC_ENTITY
enum nrf_cloud_rest_agps_req_type

nRF Cloud AGPS REST request types

Values:

enumerator NRF_CLOUD_REST_AGPS_REQ_ASSISTANCE
enumerator NRF_CLOUD_REST_AGPS_REQ_LOCATION
enumerator NRF_CLOUD_REST_AGPS_REQ_CUSTOM
enumerator NRF_CLOUD_REST_AGPS_REQ_UNSPECIFIED

Functions

int nrf_cloud_rest_cell_pos_get(struct nrf_cloud_rest_context *const rest_ctx, struct nrf_cloud_rest_cell_pos_request const *const request, struct nrf_cloud_cell_pos_result *const result)

nRF Cloud location request.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • request – [in] Data to be provided in API call.

  • result – [inout] Optional; parsed results of API response. If NULL, user should inspect the response buffer of nrf_cloud_rest_context.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

int nrf_cloud_rest_agps_data_get(struct nrf_cloud_rest_context *const rest_ctx, struct nrf_cloud_rest_agps_request const *const request, struct nrf_cloud_rest_agps_result *const result)

nRF Cloud Assisted GPS (A-GPS) data request.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • request – [in] Data to be provided in API call.

  • result – [inout] Optional; Additional buffer for A-GPS data. This is necessary when the A-GPS data from the cloud is larger than the fragment size specified by rest_ctx->fragment_size.

Return values

0 – If successful. If result is NULL and the A-GPS data is larger than the fragment size specified by rest_ctx->fragment_size, a positive value is returned, which indicates the size (in bytes) of the necessary result buffer. Otherwise, a (negative) error code is returned:

  • -EINVAL will be returned, and an error message printed, if invalid parameters are given.

  • -ENOBUFS will be returned, and an error message printed, if there is not enough buffer space to store retrieved AGPS data.

  • See Request failure for all other possible error codes.

int nrf_cloud_rest_pgps_data_get(struct nrf_cloud_rest_context *const rest_ctx, struct nrf_cloud_rest_pgps_request const *const request)

nRF Cloud Predicted GPS (P-GPS) data request.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API. If successful, rest_ctx->result will point to the P-GPS data; which, along with rest_ctx->response_len, can be passed into nrf_cloud_pgps_process.

  • request – [in] Data to be provided in API call.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

int nrf_cloud_rest_fota_job_get(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, struct nrf_cloud_fota_job_info *const job)

Requests nRF Cloud FOTA job info for the specified device.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • job – [out] Optional; parsed job info. If no job exists, type will be set to invalid. If a job exists, user must call nrf_cloud_rest_fota_job_free to free the memory allocated by this function. If NULL, user should inspect the response buffer of nrf_cloud_rest_context.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

void nrf_cloud_rest_fota_job_free(struct nrf_cloud_fota_job_info *const job)

Frees memory allocated by nrf_cloud_rest_fota_job_get.

Parameters

  • job – [inout] Job info to be freed.

int nrf_cloud_rest_fota_job_update(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const job_id, const enum nrf_cloud_fota_status status, const char *const details)

Updates the status of the specified nRF Cloud FOTA job.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • job_id – [in] Null-terminated FOTA job identifier.

  • status – [in] Status of the FOTA job.

  • details – [in] Null-terminated string containing details of the job, such as an error description.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

int nrf_cloud_rest_shadow_state_update(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const shadow_json)

Updates the device’s “state” in the shadow via the UpdateDeviceState endpoint.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • shadow_json – [in] Null-terminated JSON string to be written to the device’s shadow.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

int nrf_cloud_rest_shadow_service_info_update(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const struct nrf_cloud_svc_info *const svc_inf)

Updates the device’s “ServiceInfo” in the shadow.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • svc_inf – [in] Service info items to be updated in the shadow.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

int nrf_cloud_rest_disconnect(struct nrf_cloud_rest_context *const rest_ctx)

Closes the connection to the server. The socket pointed to by rest_ctx.connect_socket will be closed, and rest_ctx.connect_socket will be set to -1.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

Return values

0 – If successful. Otherwise, a (negative) error code is returned:

  • -EINVAL, if valid context is not given.

  • -ENOTCONN, if socket was already closed, or never opened.

  • -EIO, for any kind of socket-level closure failure.

int nrf_cloud_rest_jitp(const sec_tag_t nrf_cloud_sec_tag)

Performs just-in-time provisioning (JITP) with nRF Cloud.

Note

After a device has been provisioned with nRF Cloud, it must be associated with an nRF Cloud account before using any other functions in this library.

Parameters

  • nrf_cloud_sec_tag – [in] Modem sec_tag containing nRF Cloud JITP credentials

Return values

  • 0 – If successful; wait 30s before associating device with nRF Cloud account.

  • 1 – Device is already provisioned. Otherwise, a (negative) error code is returned:

    • Any underlying socket or HTTP response error will be returned directly.

    • -ENODEV will be returned if device JITP immediately rejected.

int nrf_cloud_rest_send_device_message(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const json_msg, const bool bulk, const char *const topic)

Send a JSON formatted device message using the SendDeviceMessage endpoint.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • json_msg – [in] Null-terminated JSON string containing the device message.

  • bulk – [in] Use the bulk message topic. If true, the topic parameter is ignored.

  • topic – [in] Optional; null-terminated MQTT topic string. If NULL, the d2c topic is used.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

int nrf_cloud_rest_send_location(struct nrf_cloud_rest_context *const rest_ctx, const char *const device_id, const char *const nmea_sentence, const int64_t ts_ms)

Send a supported NMEA sentence to nRF Cloud as a device message.

Parameters

  • rest_ctx – [inout] Context for communicating with nRF Cloud’s REST API.

  • device_id – [in] Null-terminated, unique device ID registered with nRF Cloud.

  • nmea_sentence – [in] Null-terminated NMEA sentence.

  • ts_ms – [in] UNIX epoch timestamp (in milliseconds) to include with the location data. A negative value will exclude the timestamp.

Return values

0 – If successful. Otherwise, a (negative) error code is returned. See Request failure for details.

struct nrf_cloud_rest_context
#include <nrf_cloud_rest.h>

Parameters and data for using the nRF Cloud REST API.

Public Members

int connect_socket

Connection socket; initialize to -1 and library will make the connection.

bool keep_alive

If the connection should remain after API call.

Note

A failed API call could result in the socket being closed.

int32_t timeout_ms

Timeout value, in milliseconds, for receiving response data. Minimum timeout value specified by NRF_CLOUD_REST_TIMEOUT_MINIMUM. For no timeout, set to NRF_CLOUD_REST_TIMEOUT_NONE.

Note

This parameter is currently not used; set CONFIG_REST_CLIENT_SCKT_RECV_TIMEOUT instead.

char *auth

Authentication string: JWT JWT generation. The nRF Cloud device ID must be included in the sub claim. If the device ID is the device’s internal UUID, the sub claim can be omitted for modem generated JWTs; the UUID is included in the iss claim. If no JWT is provided, and CONFIG_NRF_CLOUD_REST_AUTOGEN_JWT is enabled, then one will be generated automatically with CONFIG_NRF_CLOUD_REST_AUTOGEN_JWT_VALID_TIME_S as its lifetime in seconds.

char *rx_buf

User allocated buffer for receiving API response, which includes the HTTPS headers, any response data and a terminating NULL. Buffer size should be limited according to the maximum TLS receive size of the modem.

size_t rx_buf_len

Size of rx_buf

size_t fragment_size

Fragment size for downloads, set to zero to use CONFIG_NRF_CLOUD_REST_FRAGMENT_SIZE. The rx_buf must be able to hold the HTTPS headers plus this fragment size.

enum nrf_cloud_http_status status

Results from API call HTTP status of API call

char *response

Start of response content data in rx_buf

size_t response_len

Length of response content data

size_t total_response_len

Length of HTTPS headers + response content data

enum nrf_cloud_error nrf_err

Error code from nRF Cloud

struct nrf_cloud_rest_cell_pos_request
#include <nrf_cloud_rest.h>

Data required for nRF Cloud cellular positioning request.

Public Members

struct lte_lc_cells_info *net_info

Network information used in request

struct nrf_cloud_rest_agps_request
#include <nrf_cloud_rest.h>

Data required for nRF Cloud Assisted GPS (A-GPS) request.

Public Members

struct nrf_modem_gnss_agps_data_frame *agps_req

Required for custom request type

struct lte_lc_cells_info *net_info

Optional; provide network info or set to NULL. The cloud cannot provide location assistance data if network info is NULL.

bool filtered

Reduce set of ephemerides to only those visible at current location. This reduces the overall size of the download, but may increase fix times towards the end of the validity period and/or if the device is actively traveling long distances.

uint8_t mask_angle

Constrain the set of ephemerides to only those currently visible at or above the specified elevation threshold angle in degrees. Range is 0 to 90.

struct nrf_cloud_rest_agps_result
#include <nrf_cloud_rest.h>

nRF Cloud Assisted GPS (A-GPS) result

Public Members

char *buf

User-provided buffer to hold AGPS data

size_t buf_sz

Size of user-provided buffer

size_t agps_sz

Size of the AGPS data copied into buffer

struct nrf_cloud_rest_pgps_request
#include <nrf_cloud_rest.h>

Data required for nRF Cloud Predicted GPS (P-GPS) request.

Public Members

const struct gps_pgps_request *pgps_req

Data to be included in the P-GPS request. To omit an item use the appropriate define in Omit item from P-GPS request.