migration-guides.md

Migration guides

⭐ Switching from other HTTP request libraries to Got ⭐

Migrating from Request

You may think it's too hard to switch, but it's really not. 🦄

Let's take the very first example from Request's readme:

const request = require('request');

request('https://google.com', (error, response, body) => {
	console.log('error:', error);
	console.log('statusCode:', response && response.statusCode);
	console.log('body:', body);
});

With Got, it is:

const got = require('got');

(async () => {
	try {
		const response = await got('https://google.com');
		console.log('statusCode:', response.statusCode);
		console.log('body:', response.body);
	} catch (error) {
		console.log('error:', error);
	}
})();

Looks better now, huh? 😎

Common options

Both Request and Got accept http.request options.

These Got options are the same as with Request:

• url (+ we accept URL instances too!)
• body
• followRedirect
• encoding
• maxRedirects

So if you're familiar with them, you're good to go.

Oh, and one more thing... There's no time option. Assume it's always true.

Renamed options

Readability is very important to us, so we have different names for these options:

• qs → searchParams
• strictSSL → rejectUnauthorized
• gzip → decompress
• jar → cookieJar (accepts tough-cookie jar)

It's more clear, isn't it?

Changes in behavior

The timeout option has some extra features. You can set timeouts on particular events!

The searchParams option is always serialized using URLSearchParams unless it's a string.

To use streams, just call got.stream(url, options) or got(url, {isStream: true, ...}).

Breaking changes

• The json option is not a boolean, it's an Object. It will be stringified and used as a body.
• The form option is an Object. It can be a plain object or a form-data instance.
• No oauth/hawk/aws/httpSignature option. To sign requests, you need to create a custom instance.
• No agentClass/agentOptions/pool option.
• No forever option. You need to use forever-agent.
• No proxy option. You need to pass a custom agent.
• No auth option. You need to use username / password instead.
• No baseUrl option. Instead, there is prefixUrl which appends a trailing slash if not present. It will be always prepended unless url is an instance of URL.
• No removeRefererHeader option. You can remove the referer header in a beforeRequest hook:

const gotInstance = got.extend({
	hooks: {
		beforeRequest: [
			options => {
				delete options.headers.referer;
			}
		]
	}
});

gotInstance(url, options);

• No jsonReviver/jsonReplacer option, but you can use hooks for that too:

const gotInstance = got.extend({
	hooks: {
		init: [
			options => {
				if (options.jsonReplacer && options.json) {
					options.body = JSON.stringify(options.json, options.jsonReplacer);
					delete options.json;
				}
			}
		],
		afterResponse: [
			response => {
				const {options} = response.request;
				if (options.jsonReviver && options.responseType === 'json') {
					options.responseType = 'text';
					response.body = JSON.parse(response.body, options.jsonReviver);
				}

				return response;
			}
		]
	}
});

gotInstance(url, options);

Hooks are powerful, aren't they? Read more to see what else you achieve using hooks.

More about streams

Let's take a quick look at another example from Request's readme:

http.createServer((request, response) => {
	if (request.url === '/doodle.png') {
		request.pipe(request('https://example.com/doodle.png')).pipe(response);
	}
});

The cool feature here is that Request can proxy headers with the stream, but Got can do that too:

const stream = require('stream');
const {promisify} = require('util');
const got = require('got');

const pipeline = promisify(stream.pipeline);

http.createServer(async (request, response) => {
	if (request.url === '/doodle.png') {
		// When someone makes a request to our server, we receive a body and some headers.
		// These are passed to Got. Got proxies downloaded data to our server response,
		// so you don't have to do `response.writeHead(statusCode, headers)` and `response.end(body)`.
		// It's done automatically.
		await pipeline(
			got.stream('https://example.com/doodle.png'),
			response
		);
	}
});

Nothing has really changed. Just remember to use got.stream(url, options) or got(url, {isStream: true, …}). That's it!

You're good to go!

Well, you have already come this far 🎉 Take a look at the documentation. It's worth the time to read it. There are some great tips. If something is unclear or doesn't work as it should, don't hesitate to open an issue.