# HTTP Client

## Our header, your implementation

We provide functions signatures in `vertices_http.h` .

The SDK will call those functions when needed.

### Client Init/DeInit

The `http_init` function is called on Vertices SDK initialization.

```c
/// Init HTTP client
/// \param provider Remote API URL, port, specific header and certificate if needed by the client
/// \param response_payload_cb Function callback to call when data is ready to be parsed
/// \return \c VTC_SUCCESS on success, otherwise error depends on implementation
ret_code_t
http_init(const provider_info_t *provider,
          size_t (*response_payload_cb)(char *chunk,
                                        size_t chunk_size));

/// Close/deinit the client
void
http_close(void);
```

The init function is simple: all you have to do is to init the HTTP client using the parameters. The URL, port, specific headers, and certificates are passed with the `provider` parameter. 

The callback function `reponse_payload_cb` must be kept locally as we will need to call it whenever a response is received after a `GET` or a `POST` method call.

#### The callback

The callback function will be called whenever an HTTP response body is ready to be parsed: a pointer to the received bytes `chunk` and the size `chunk_size` will be provided to the Vertices SDK when calling the callback. The buffer can be a pointer allocated by the underlying HTTP client.

### GET/POST methods

```c
/// HTTP GET request
/// \param provider pointer to provider (url, port..)
/// \param relative_path path to append to the provider base URL
/// \param headers Headers string, each one must have the format "key:value\n\r"
/// \param response_code HTTP response code
/// \return error codes:
/// - \c VTC_SUCCESS on success
/// - \c VTC_ERROR_OFFLINE if offline
/// - \c VTC_HTTP_ERROR on HTTP error: check response_code.
ret_code_t
http_get(const provider_info_t *provider,
         const char *relative_path,
         const char *headers,
         uint32_t *response_code);

/// HTTP POST request
/// \param provider pointer to provider (url, port..)
/// \param relative_path path to append to the provider base URL
/// \param headers Headers string, each one must have the format "key:value\n\r"
/// \param body HTTP body
/// \param body_size size of \c body array
/// \param response_code HTTP response code
/// \return error codes:
/// - \c VTC_SUCCESS on success
/// - \c VTC_ERROR_OFFLINE if offline
/// - \c VTC_HTTP_ERROR on HTTP error: check response_code.
ret_code_t
http_post(const provider_info_t *provider,
          const char *relative_path,
          char *headers,
          const char *body,
          size_t body_size,
          uint32_t *response_code);
```

�Some important information to keep in mind:

* The full URL is  a concatenation of  `provider->url` and `relative_path`.
* Headers are key-value pairs separated by `\r` , `\n` or both. The format of the key-value pair is as follow `key:value\n\r`.
* If the HTTP call fails, the HTTP response code must be set in `response_code` and the function must respond `VTC_HTTP_ERROR`.
* Once the full response is ready to be parsed, you will need to call the callback stored during the initialization of the module with a pointer to the raw buffer and its size: `response_payload_cb(response_data, response_length);`

Now that we are able to receive and send data using a configured provider, we are going to build transactions that will soon be sent on the blockchain. To do so, we will need to handle events.

{% hint style="info" %}
Here is [the link](https://github.com/vertices-network/sdk-porting-guide/commit/d966a30c7f421706ca2b665bba2ed5d1b829ace2) to our (partial) implementation of the above step.

For full implementation, you can take a look at our example for Unix and the ESP32, both using different HTTP clients 😉
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vertices.network/vertices-sdk/porting-guide/http-client.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.