rest : REST and HTTP functions

The REST and HTTP functions provides a framework for building and using REST APIs as well as for performing generic HTTP requests and running a simple HTTP server.

The REST and HTTP functions are only available in NX32L compilation mode.

The API uses three different types of SYSHANDLE: Server, Request and Response.

Depending on what the needed functionality is, a different set of functions will be needed:

Requesting data from remote server:

A request is created using restReqCreate and the contents of it are set using the different Request functions.

The function restClientRequest then sends the request to a server and receives the response.

The response must then be read using the Response functions.

Making data available to clients:

The server is created using restServerCreate and endpoints are added using restServerEndpointAdd.

The server is started using restServerStart and will now listen for incoming requests on the configured port.

When it receives a request, the callback for the endpoint will be called and the necessary data must be read from the request using the Request functions.

The response must be filled out using the Response functions and it will be sent back to the client.

The following REST and HTTP functions are available:

Server functions:

The server functions are used to manage the REST/HTTP server.

	•restServerCreate	Create a REST server.
	•restServerFree	Release a REST server.
	•restServerEndpointAdd	Create an endpoint on the REST server.
	•restServerStart	Starts the REST server.
	•restServerStop	Stops the REST server.

Request functions:

The request functions are used to create a request or to extract data from an incoming request.

	•restReqCreate	Create a REST request.
	•restReqFree	Free a REST request.
	•restReqHeaderKey	Read the name of a header field in a request.
	•restReqHeaderGet	Read a header field from the REST request.
	•restReqHeaderSet	Set the value of a header field in a REST request.
	•restReqQueryKey	Read the name of a query field in a request.
	•restReqQueryGet	Read a query parameter from the REST request.
	•restReqQuerySet	Set the value of a query parameter on a REST request.
	•restReqPostKey	Read the name of a post field in a request.
	•restReqPostGet	Read a post parameter from the REST request.
	•restReqPostSet	Set the value of a post parameter on a REST request.
	•restReqBasicAuthGet	Read the basic authentication provided from the client.
	•restReqBasicAuthSet	Set the basic authentication to use.
	•restReqBodyGetString	Get the contents of the body of the REST request as a string.
	•restReqBodySetString	Set the body content of the REST request to the provided string.
	•restReqBodyGetJSON	Get the contents of the body of the REST request as a JSON structure.
	•restReqBodySetJSON	Set the body content of the REST request to the provided JSON structure.
	•restReqBodySize	Return the size of the body content.
	•restReqBodyGetRaw	Copy part of the body content into a buffer.
	•restReqClientAddressGet	Get the IP address of the client that sent the request.
	•restReqUrlGet	Get the URL and method of the request.

Request Client certificate functions:

The client certificate functions are used to set and examine the client certificate used to authenticate a client with a server.

	•restReqClientCertSet	Set the client certificate of a request, it will be sent to the server
	•restReqClientCertPresent	Check if the incoming request contains a client certificate
	•restReqClientCertSubjectGet	Get the subject of the client certificate
	•restReqClientCertSubjectCNGet	Get the subject common name(CN) from the client certificate
	•restReqClientCertIssuerGet	Get the issuer of the client certificate
	•restReqClientCertVersionGet	Get the version of the client certificate format
	•restReqClientCertValidFrom	Get the start of the valid date range of the client certificate
	•restReqClientCertValidTo	Get the end of the valid date range of the client certificate
	•restReqClientCertSerialGet	Get the serial number of the client certificate
	•restReqClientCertFingerprintGet	Get the fingerprint of the client certificate
	•restReqClientCertSANGet	Get a Subject Alternative Name (SAN) for the client certificate.
	•restReqClientCertCheckHostname	Check if the subject of the certificate matches the provided hostname.
	•restReqClientCertCheckEmail	Check if the certificate matches the provided email address.

Response functions:

The response functions are used to extract data from a response to a request or to build the response to send for a request.

	•restRespFree	Free a REST response.
	•restRespBodySetString	Set the body content of the REST response to the provided string.
	•restRespBodyGetString	Get the contents of the body of the REST response as a string.
	•restRespBodySetJSON	Set the body content of the REST response to the provided JSON structure.
	•restRespBodyGetJSON	Get the contents of the body of the REST response as a JSON structure.
	•restRespBodySize	Return the size of the body content.
	•restRespBodyGetRaw	Copy part of the body content into a buffer.
	•restRespHeaderKey	Read the name of a header field in a response.
	•restRespHeaderGet	Read a header field from the REST response.
	•restRespHeaderSet	Set the value of a header field in a REST response.
	•restRespBasicAuthSet	Make the response request basic authentication on status 401.

Client functions:

•restClientRequest

Execute a REST client request and wait for the response.