Skip to content

Latest commit

 

History

History
143 lines (107 loc) · 4.87 KB

http-client.md

File metadata and controls

143 lines (107 loc) · 4.87 KB
Raw

HTTP Client

Introduction

Hunt Framework provides an expressive, minimal API around the Hunt HTTP client, allowing you to quickly make outgoing HTTP requests to communicate with other web applications. Hunt Framework's wrapper around Hunt HTTP client is focused on its most common use cases and a wonderful developer experience.

Before getting started, you should ensure that you have installed the Hunt HttpClient package as a dependency of your application. By default, Hunt Framework Does Not include this dependency:

dub add hunt-httpclient

Making Requests

To make requests, you may use the get, post, put, patch, and delete methods. First, let's examine how to make a basic GET request:

import hunt.httpclient;

auto response = Http.get("http://test.com");

The get method returns an instance of Response in module hunt.httpclient.Response, which provides a variety of methods that may be used to inspect the response:

string content();
JSONValue json();
int status();
bool isOk();
bool isSuccessful();
bool isFailed();
bool isClientError();
bool isServerError();
Cookie[] cookies();
HttpField[] headers();
string[] header(string name);

The Response object also overloads the index operator, allowing you to access JSON response data directly on the response:

return Http.get("http://test.com/users/1")["name"];

Request Data

Of course, it is common when using POST, PUT, and PATCH to send additional data with your request. So, these methods accept an array of data as their second argument. By default, data will be sent using the application/json content type:

auto response = Http.post("http://test.com/users", [
    "name" : "Steve",
    "role" : "Network Administrator",
]);

Sending Form URL Encoded Requests

If you would like to send data using the application/x-www-form-urlencoded content type, you should call the asForm method before making your request:

auto response = Http.asForm().post("http://test.com/users", [
    "name" : "Sara",
    "role" : "Privacy Consultant",
]);

Multi-Part Requests

If you would like to send files as multi-part requests, you should call the attach method before making your request. This method accepts the name of the file. Optionally, you may provide a third argument which will be considered the custom headers:

auto response = Http.attach(
    "attachment", "photo.jpg"
).post("http://test.com/attachments");

Headers

Headers may be added to requests using the withHeaders method. This withHeaders method accepts an array of key / value pairs:

auto response = Http.withHeaders([
    "X-First" : "foo",
    "X-Second" : "bar"
]).post("http://test.com/users", [
    "name" : "Taylor",
]);

Bearer Tokens

If you would like to quickly add an Authorization bearer token header to the request, you may use the withToken method:

auto response = Http.withToken("token").post(...);

Timeout

The timeout method may be used to specify the maximum time to wait for a response:

auto response = Http.timeout(3.seconds).get(...);

If the given timeout is exceeded, an instance of TimeoutException will be thrown.

Retries

If you would like HTTP client to automatically retry the request if a client or server error occurs, you may use the retry method. The retry method accepts two arguments: the number of times the request should be attempted and the interval that Hunt Client should wait in between attempts:

auto response = Http.retry(3, 100.msecs).post(...);

If all of the requests fail, an instance of Exception will be thrown.

Error Handling

Hunt's HTTP client wrapper does not throw exceptions on client or server errors (400 and 500 level responses from servers). You may determine if one of these errors was returned using the successful, clientError, or serverError methods:

// Determine if the status code was >= 200 and < 300...
response.successful();

// Determine if the status code was >= 400...
response.failed();

// Determine if the response has a 400 level status code...
response.clientError();

// Determine if the response has a 500 level status code...
response.serverError();