# 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 %}