0
# HTTP Utilities
1

2
URL handling, header management, media type parsing, and HTTP protocol utilities.
3

4
## Capabilities
5

6
### HttpUrl
7

8
HTTP/HTTPS URL with parsing, encoding, and building capabilities.
9

10
```java { .api }
11
public final class HttpUrl {
12
    public static HttpUrl parse(String url);
13
    public static HttpUrl get(URL url);
14
    public static HttpUrl get(URI uri);
15
    public static int defaultPort(String scheme);
16
    public URL url();
17
    public URI uri();
18
    public String scheme();
19
    public boolean isHttps();
20
    public String host();
21
    public int port();
22
    public String encodedPath();
23
    public List<String> pathSegments();
24
    public String encodedQuery();
25
    public String query();
26
    public String queryParameter(String name);
27
    public List<String> queryParameterValues(String name);
28
    public Set<String> queryParameterNames();
29
    public String encodedFragment();
30
    public String fragment();
31
    public String redact();
32
    public HttpUrl resolve(String link);
33
    public Builder newBuilder();
34
    public Builder newBuilder(String link);
35
    
36
    public static final class Builder {
37
        public Builder();
38
        public Builder scheme(String scheme);
39
        public Builder username(String username);
40
        public Builder password(String password);
41
        public Builder host(String host);
42
        public Builder port(int port);
43
        public Builder addPathSegment(String pathSegment);
44
        public Builder addEncodedPathSegment(String encodedPathSegment);
45
        public Builder setPathSegment(int index, String pathSegment);
46
        public Builder setEncodedPathSegment(int index, String encodedPathSegment);
47
        public Builder removePathSegment(int index);
48
        public Builder encodedPath(String encodedPath);
49
        public Builder query(String query);
50
        public Builder encodedQuery(String encodedQuery);
51
        public Builder addQueryParameter(String name, String value);
52
        public Builder addEncodedQueryParameter(String name, String value);
53
        public Builder setQueryParameter(String name, String value);
54
        public Builder setEncodedQueryParameter(String name, String value);
55
        public Builder removeAllQueryParameters(String name);
56
        public Builder fragment(String fragment);
57
        public Builder encodedFragment(String encodedFragment);
58
        public HttpUrl build();
59
    }
60
}
61
```
62

63
**Usage Examples:**
64

65
```java
66
// Parse and build URLs
67
HttpUrl url = HttpUrl.parse("https://api.example.com/users");
68
HttpUrl newUrl = url.newBuilder()
69
    .addQueryParameter("page", "2")
70
    .addQueryParameter("limit", "50")
71
    .build();
72

73
// Build URL from scratch
74
HttpUrl builtUrl = new HttpUrl.Builder()
75
    .scheme("https")
76
    .host("api.example.com")
77
    .addPathSegment("v1")
78
    .addPathSegment("users")
79
    .addQueryParameter("active", "true")
80
    .fragment("top")
81
    .build();
82

83
// URL manipulation
84
HttpUrl baseUrl = HttpUrl.parse("https://example.com/api");
85
HttpUrl resolvedUrl = baseUrl.resolve("../v2/users?sort=name");
86

87
// Access URL components
88
String scheme = url.scheme();        // "https"
89
String host = url.host();           // "api.example.com"
90
int port = url.port();              // 443 (default HTTPS port)
91
List<String> segments = url.pathSegments(); // ["users"]
92
String queryParam = url.queryParameter("page"); // "2"
93
```
94

95
### URL Building
96

97
Construct URLs programmatically with the HttpUrl.Builder.
98

99
```java { .api }
100
/**
101
 * Builder for constructing HttpUrl instances.
102
 */
103
public static final class Builder {
104
    public Builder();
105
    public Builder scheme(String scheme);
106
    public Builder username(String username);
107
    public Builder password(String password);
108
    public Builder host(String host);
109
    public Builder port(int port);
110
    public Builder addPathSegment(String pathSegment);
111
    public Builder addEncodedPathSegment(String encodedPathSegment);
112
    public Builder setPathSegment(int index, String pathSegment);
113
    public Builder setEncodedPathSegment(int index, String encodedPathSegment);
114
    public Builder removePathSegment(int index);
115
    public Builder encodedPath(String encodedPath);
116
    public Builder query(String query);
117
    public Builder encodedQuery(String encodedQuery);
118
    public Builder addQueryParameter(String name, String value);
119
    public Builder addEncodedQueryParameter(String name, String value);
120
    public Builder setQueryParameter(String name, String value);
121
    public Builder setEncodedQueryParameter(String name, String value);
122
    public Builder removeAllQueryParameters(String name);
123
    public Builder fragment(String fragment);
124
    public Builder encodedFragment(String encodedFragment);
125
    public HttpUrl build();
126
}
127
```
128

129
**Usage Examples:**
130

131
```java
132
// Complex URL building
133
HttpUrl complexUrl = new HttpUrl.Builder()
134
    .scheme("https")
135
    .username("user")
136
    .password("pass")
137
    .host("secure.api.example.com")
138
    .port(8443)
139
    .addPathSegment("api")
140
    .addPathSegment("v2")
141
    .addPathSegment("search")
142
    .addQueryParameter("q", "java http client")
143
    .addQueryParameter("limit", "10")
144
    .addQueryParameter("sort", "relevance")
145
    .fragment("results")
146
    .build();
147

148
// Dynamic query building
149
HttpUrl.Builder builder = HttpUrl.parse("https://api.example.com/search").newBuilder();
150
Map<String, String> filters = getSearchFilters();
151
for (Map.Entry<String, String> filter : filters.entrySet()) {
152
    builder.addQueryParameter(filter.getKey(), filter.getValue());
153
}
154
HttpUrl searchUrl = builder.build();
155

156
// Path manipulation
157
HttpUrl apiUrl = new HttpUrl.Builder()
158
    .scheme("https")
159
    .host("api.example.com")
160
    .addPathSegment("users")
161
    .addPathSegment("123")
162
    .addPathSegment("profile")
163
    .build(); // https://api.example.com/users/123/profile
164
```
165

166
### Headers
167

168
Immutable HTTP headers collection with case-insensitive name matching.
169

170
```java { .api }
171
public final class Headers {
172
    public static Headers of(String... namesAndValues);
173
    public static Headers of(Map<String, String> headers);
174
    public String get(String name);
175
    public Date getDate(String name);
176
    public int size();
177
    public String name(int index);
178
    public String value(int index);
179
    public Set<String> names();
180
    public List<String> values(String name);
181
    public Builder newBuilder();
182
    public Map<String, List<String>> toMultimap();
183
}
184
```
185

186
### MediaType
187

188
RFC 2045 Media Type for HTTP content with parsing capabilities.
189

190
```java { .api }
191
public final class MediaType {
192
    public static MediaType parse(String string);
193
    public String type();
194
    public String subtype();
195
    public Charset charset();
196
    public Charset charset(Charset defaultValue);
197
}
198
```
199

200
**Usage Examples:**
201

202
```java
203
// Work with headers
204
Headers headers = new Headers.Builder()
205
    .add("Content-Type", "application/json")
206
    .add("Authorization", "Bearer token")
207
    .build();
208

209
// Access header values
210
String contentType = headers.get("Content-Type");
211
List<String> acceptValues = headers.values("Accept");
212
Set<String> headerNames = headers.names();
213

214
// Convert to map
215
Map<String, List<String>> headerMap = headers.toMultimap();
216

217
// Parse media types
218
MediaType json = MediaType.parse("application/json; charset=utf-8");
219
Charset charset = json.charset(); // UTF-8
220

221
// Media type operations
222
MediaType plainText = MediaType.parse("text/plain");
223
String type = plainText.type();        // "text"
224
String subtype = plainText.subtype();  // "plain"
225
```
226

227
### Credentials
228

229
Utility class for creating HTTP authentication credentials.
230

231
```java { .api }
232
public final class Credentials {
233
    public static String basic(String userName, String password);
234
}
235
```
236

237
**Usage Examples:**
238

239
```java
240
// Basic authentication
241
String authHeader = Credentials.basic("user123", "secretpass");
242
Request request = new Request.Builder()
243
    .url("https://api.example.com/protected")
244
    .header("Authorization", authHeader)
245
    .build();
246

247
// Use with interceptor
248
client.interceptors().add(new Interceptor() {
249
    @Override
250
    public Response intercept(Chain chain) throws IOException {
251
        Request original = chain.request();
252
        Request authenticated = original.newBuilder()
253
            .header("Authorization", Credentials.basic("username", "password"))
254
            .build();
255
        return chain.proceed(authenticated);
256
    }
257
});
258
```