EmbedThis

Appearance

URL HTTP Client ​

The Ioto URL API is a HTTP client for interacting with HTTP servers. It is a full-duplex streaming HTTP client that can retrieve both documents and live streaming data. The URL client supports both HTTP and WebSockets over HTTP.

The URL client uses a fiber coroutines to that you can write natural, blocking, procedural code without ugly callbacks or complex threads. It is a highly efficient HTTP and WebSockets client that uses minimal CPU from only 11K of code.

URL Features ​

  • HTTP/1.0, HTTP.1.1 client.
  • WebSockets client.
  • Fully streaming API for dynamic input and output.
  • Convenience JSON API for interacting with REST services.
  • Single-threaded, fiber coroutine event-based runtime without ugly callbacks or complex threads.
  • TLS/SSL 1.3 with certificate verification controls.

API Quick Tour ​

The URL API provides a high-level simple API and a lower-level API with more granular control.

The high-level API consists of the routines urlGet and urlPost.

Get Request ​

To get a remote document, use the urlGet API:

c
char *document = urlGet("https://example.com/index.html", headers);
printf("Document %s\n", document);
rFree(document);

This call will block the current fiber while other fibers continue to run. When the document has been retrieved, the call will resume and the document will be returned. If the request fails and a non-200 HTTP status is returned, the call returns NULL. When complete, you must free the returned string using rFree.

HTTP Headers ​

To supply headers with your requests, you can use the headers printf style arguments:

c
urlGet("https://example.com/data", "Authorization: %s\r\n", password);

Each header in the format string must be separated by "\r\n".

Post Request ​

To issue a post request, use urlPost API

c
char *document = urlPost("https://my.com/post", data, dataLength, httpHeaders);

If the data is a string, you can set the length to be -1 and the length will be calculated from the string. The last NULL argument is for optional HTTP headers.

char *document = urlPost("https://my.com/post", "Hello World", -1, NULL);

JSON Responses ​

If you want to issue a POST request and retrieve a JSON document, you can use the JSON variants urlPostJson:

c
Json *json = urlPostJson("https://my.com/", data, dataLength, NULL);
jsonPrint(json);

Use the JSON APIs to manage the returned JSON in-memory tree result.

WebSockets ​

To start a WebSockets session, use the urlWebSockets API:

c
int status = urlWebSocket("https://my.com/post", onRead, NULL, NULL);

// This return zero when closed, otherwise a negative status code.

void onRead(WebSocket *ws, char *buf, ssize len, void *arg)
{
    printf("Received %s\n", buf);
    webSocketSend(ws, "%s", "Response message");
}

See URL WebSockets for details.

Low Level API ​

The URL client also offers a low-level API for granular control.

API ​