0
# HTTP Methods
1

2
Core HTTP method functions for making requests with fluent chainable interface. All methods return a Request instance that can be configured and executed.
3

4
## Capabilities
5

6
### GET Method
7

8
Performs HTTP GET requests for retrieving data.
9

10
```javascript { .api }
11
/**
12
 * Create a GET request
13
 * @param {string} url - Request URL
14
 * @param {object|function} [data] - Query parameters or callback function
15
 * @param {function} [callback] - Callback function
16
 * @returns {Request} Request instance for chaining
17
 */
18
function get(url, data?, callback?): Request;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const superagent = require('superagent');
25

26
// Basic GET request
27
superagent.get('https://api.example.com/users');
28

29
// GET with query parameters
30
superagent.get('https://api.example.com/users', { page: 1, limit: 10 });
31

32
// GET with callback shorthand
33
superagent.get('https://api.example.com/users', (err, res) => {
34
  console.log(res.body);
35
});
36
```
37

38
### POST Method
39

40
Performs HTTP POST requests for creating or submitting data.
41

42
```javascript { .api }
43
/**
44
 * Create a POST request
45
 * @param {string} url - Request URL
46
 * @param {any} [data] - Request body data or callback function
47
 * @param {function} [callback] - Callback function
48
 * @returns {Request} Request instance for chaining
49
 */
50
function post(url, data?, callback?): Request;
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
// POST with JSON data
57
superagent
58
  .post('https://api.example.com/users')
59
  .send({ name: 'John', email: 'john@example.com' });
60

61
// POST with form data
62
superagent
63
  .post('https://api.example.com/login')
64
  .type('form')
65
  .send({ username: 'user', password: 'pass' });
66
```
67

68
### PUT Method
69

70
Performs HTTP PUT requests for updating or replacing resources.
71

72
```javascript { .api }
73
/**
74
 * Create a PUT request
75
 * @param {string} url - Request URL
76
 * @param {any} [data] - Request body data or callback function
77
 * @param {function} [callback] - Callback function
78
 * @returns {Request} Request instance for chaining
79
 */
80
function put(url, data?, callback?): Request;
81
```
82

83
### PATCH Method
84

85
Performs HTTP PATCH requests for partial updates to resources.
86

87
```javascript { .api }
88
/**
89
 * Create a PATCH request
90
 * @param {string} url - Request URL
91
 * @param {any} [data] - Request body data or callback function
92
 * @param {function} [callback] - Callback function
93
 * @returns {Request} Request instance for chaining
94
 */
95
function patch(url, data?, callback?): Request;
96
```
97

98
### DELETE Method
99

100
Performs HTTP DELETE requests for removing resources. Available as both `delete` and `del`.
101

102
```javascript { .api }
103
/**
104
 * Create a DELETE request
105
 * @param {string} url - Request URL
106
 * @param {any} [data] - Request body data or callback function
107
 * @param {function} [callback] - Callback function
108
 * @returns {Request} Request instance for chaining
109
 */
110
function delete(url, data?, callback?): Request;
111
function del(url, data?, callback?): Request; // Alias for delete
112
```
113

114
### HEAD Method
115

116
Performs HTTP HEAD requests for retrieving headers without response body.
117

118
```javascript { .api }
119
/**
120
 * Create a HEAD request
121
 * @param {string} url - Request URL
122
 * @param {any} [data] - Query parameters or callback function
123
 * @param {function} [callback] - Callback function
124
 * @returns {Request} Request instance for chaining
125
 */
126
function head(url, data?, callback?): Request;
127
```
128

129
### OPTIONS Method
130

131
Performs HTTP OPTIONS requests for retrieving allowed methods and CORS preflight.
132

133
```javascript { .api }
134
/**
135
 * Create an OPTIONS request
136
 * @param {string} url - Request URL
137
 * @param {any} [data] - Request body data or callback function
138
 * @param {function} [callback] - Callback function
139
 * @returns {Request} Request instance for chaining
140
 */
141
function options(url, data?, callback?): Request;
142
```
143

144
### Generic Request Method
145

146
Creates requests with custom HTTP methods.
147

148
```javascript { .api }
149
/**
150
 * Create a request with custom method
151
 * @param {string} method - HTTP method
152
 * @param {string} url - Request URL
153
 * @returns {Request} Request instance for chaining
154
 */
155
function request(method, url): Request;
156

157
// Shorthand syntax
158
function request(url): Request; // Defaults to GET
159
function request(url, callback): Request; // GET with callback
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
// Custom HTTP method
166
superagent('PROPFIND', 'https://webdav.example.com/folder/');
167

168
// Default GET
169
superagent('https://api.example.com/users');
170

171
// GET with callback
172
superagent('https://api.example.com/users', (err, res) => {
173
  console.log(res.body);
174
});
175
```
176

177
## Method Behavior
178

179
### Data Parameter Handling
180

181
- **GET/HEAD**: Data is converted to query parameters
182
- **POST/PUT/PATCH/DELETE**: Data is sent as request body
183
- **Function as data**: Treated as callback function
184

185
### Callback Shortcuts
186

187
All methods support callback shortcuts for immediate execution:
188

189
```javascript
190
// Long form
191
superagent.get('https://api.example.com/users').end((err, res) => {
192
  // handle response
193
});
194

195
// Shortcut
196
superagent.get('https://api.example.com/users', (err, res) => {
197
  // handle response
198
});
199
```
200

201
### Automatic Content-Type
202

203
Methods automatically set appropriate Content-Type headers:
204

205
- **JSON data**: `application/json`
206
- **Form data**: `application/x-www-form-urlencoded`
207
- **String data**: `text/plain` (unless otherwise specified)
208
- **Buffer data**: `application/octet-stream`