0
# HTTP Request Methods
1

2
Low-level HTTP request methods for direct API access and custom endpoints not covered by higher-level methods.
3

4
## Capabilities
5

6
### GET Request
7

8
Performs HTTP GET requests to Tumblr API endpoints.
9

10
```javascript { .api }
11
/**
12
 * Performs a GET request
13
 * @param apiPath - URL path for the request (e.g., '/v2/blog/myblog/info')
14
 * @param params - Query parameters as object
15
 * @returns Promise resolving to API response
16
 */
17
getRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
// Get blog info with parameters
24
const blogInfo = await client.getRequest('/v2/blog/staff/info', {
25
  'fields[blogs]': 'name,title,description'
26
});
27

28
// Get posts with query parameters
29
const posts = await client.getRequest('/v2/blog/staff/posts', {
30
  type: 'photo',
31
  limit: 10,
32
  offset: 0
33
});
34

35
// Array parameters are automatically formatted
36
const taggedPosts = await client.getRequest('/v2/tagged', {
37
  tag: ['cats', 'funny']  // Becomes tag[0]=cats&tag[1]=funny
38
});
39
```
40

41
### POST Request
42

43
Performs HTTP POST requests to Tumblr API endpoints.
44

45
```javascript { .api }
46
/**
47
 * Performs a POST request
48
 * @param apiPath - URL path for the request
49
 * @param params - Request body parameters
50
 * @returns Promise resolving to API response
51
 */
52
postRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
53
```
54

55
**Usage Examples:**
56

57
```javascript
58
// Create a legacy post
59
const newPost = await client.postRequest('/v2/blog/myblog/post', {
60
  type: 'text',
61
  title: 'Hello World',
62
  body: 'This is my first post!'
63
});
64

65
// Like a post
66
await client.postRequest('/v2/user/like', {
67
  id: '12345',
68
  reblog_key: 'abc123'
69
});
70

71
// Follow a blog
72
await client.postRequest('/v2/user/follow', {
73
  url: 'example.tumblr.com'
74
});
75
```
76

77
### PUT Request
78

79
Performs HTTP PUT requests to Tumblr API endpoints.
80

81
```javascript { .api }
82
/**
83
 * Performs a PUT request
84
 * @param apiPath - URL path for the request
85
 * @param params - Request body parameters
86
 * @returns Promise resolving to API response
87
 */
88
putRequest(apiPath: string, params?: Record<string, any>): Promise<any>;
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
// Edit a post
95
await client.putRequest('/v2/blog/myblog/posts/12345', {
96
  content: [
97
    {
98
      type: 'text',
99
      text: 'Updated post content'
100
    }
101
  ]
102
});
103
```
104

105
## Request Processing Details
106

107
### Parameter Handling
108

109
Different parameter handling based on request method and content type:
110

111
**GET Requests:**
112
- All parameters converted to query string
113
- Arrays formatted as `param[0]=value1&param[1]=value2`
114
- Objects flattened to key-value pairs
115

116
**POST/PUT Requests:**
117
- Parameters sent in request body
118
- JSON encoding for simple data
119
- Multipart/form-data for media uploads
120

121
### Content Type Detection
122

123
The client automatically determines content type based on parameters:
124

125
```javascript
126
// JSON content-type (application/json)
127
await client.postRequest('/v2/blog/myblog/post', {
128
  type: 'text',
129
  title: 'Simple post'
130
});
131

132
// Multipart content-type (multipart/form-data)
133
await client.postRequest('/v2/blog/myblog/posts', {
134
  json: JSON.stringify({ content: [...] }),
135
  0: fs.createReadStream('image.jpg')  // Media upload
136
});
137
```
138

139
### Authentication Integration
140

141
HTTP methods automatically apply authentication based on client configuration:
142

143
```javascript
144
// API key authentication (query parameter)
145
const apiKeyClient = tumblr.createClient({ consumer_key: 'key' });
146
await apiKeyClient.getRequest('/v2/blog/staff/info');
147
// Requests: GET /v2/blog/staff/info?api_key=key
148

149
// OAuth authentication (Authorization header)
150
const oauthClient = tumblr.createClient({
151
  consumer_key: 'key',
152
  consumer_secret: 'secret',
153
  token: 'token',
154
  token_secret: 'token_secret'
155
});
156
await oauthClient.postRequest('/v2/user/info');
157
// Includes: Authorization: OAuth oauth_consumer_key="key", oauth_signature="...", ...
158
```
159

160
### Request Headers
161

162
All requests include standard headers:
163

164
```javascript
165
{
166
  'User-Agent': 'tumblr.js/5.0.1',
167
  'Accept': 'application/json',
168
  'Content-Type': 'application/json' | 'multipart/form-data'  // Based on content
169
}
170
```
171

172
### Array Parameter Formatting
173

174
Arrays are automatically formatted for Tumblr API expectations:
175

176
```javascript
177
// Input
178
await client.getRequest('/v2/tagged', {
179
  tag: ['cats', 'funny', 'gifs']
180
});
181

182
// Query string
183
// ?tag[0]=cats&tag[1]=funny&tag[2]=gifs
184

185
// Post body arrays
186
await client.postRequest('/v2/blog/myblog/posts', {
187
  tags: ['technology', 'programming']
188
});
189

190
// Form data
191
// tags[0]=technology
192
// tags[1]=programming
193
```
194

195
### Error Handling
196

197
HTTP methods handle various error conditions:
198

199
```javascript
200
try {
201
  const result = await client.getRequest('/v2/blog/nonexistent/info');
202
} catch (error) {
203
  // API errors
204
  console.log(error.message); // "API error: 404 Not Found"
205
}
206

207
try {
208
  const result = await client.postRequest('/v2/invalid-endpoint');
209
} catch (error) {
210
  // Network errors, parsing errors, etc.
211
  console.log(error.message);
212
}
213
```
214

215
### URL Construction
216

217
API paths are automatically combined with the client's base URL:
218

219
```javascript
220
const client = tumblr.createClient({
221
  baseUrl: 'https://api.tumblr.com'  // Default
222
});
223

224
// apiPath: '/v2/blog/staff/info'
225
// Full URL: https://api.tumblr.com/v2/blog/staff/info
226
await client.getRequest('/v2/blog/staff/info');
227
```
228

229
### Media Upload Support
230

231
POST and PUT requests support media uploads via Node.js streams:
232

233
```javascript
234
const fs = require('fs');
235

236
await client.postRequest('/v2/blog/myblog/posts', {
237
  json: JSON.stringify({
238
    content: [
239
      {
240
        type: 'image',
241
        media: { identifier: '0' },
242
        alt_text: 'My photo'
243
      }
244
    ]
245
  }),
246
  0: fs.createReadStream('./photo.jpg')  // Stream mapped to identifier
247
});
248
```
249

250
### Legacy Callback Support
251

252
All HTTP methods support legacy callback patterns (deprecated):
253

254
```javascript
255
// Promise (recommended)
256
const result = await client.getRequest('/v2/blog/staff/info');
257

258
// Callback (deprecated)
259
client.getRequest('/v2/blog/staff/info', (err, result) => {
260
  if (err) {
261
    console.error(err);
262
  } else {
263
    console.log(result);
264
  }
265
});
266

267
// Callback with parameters (deprecated)
268
client.getRequest('/v2/blog/staff/posts', { limit: 5 }, (err, result) => {
269
  // Handle response
270
});
271
```