Basic documentation for 'got' object

[BryanDollery]

I don't know if I'm looking in the wrong place, but although this seems to be a pretty well-documented project, I am completely unable to find the basic documentation on the got object itself, such as the parameters for got.post() and other similar methods (presumably get, put, patch, etc.).

I've read through everything in the documentation folder and while its very useful to know how to manage streams, I'm struggling to find the basics, like whether I need to set a header when posting json or if that's automatic.

I'm sure it's here somewhere, I just can't find it.

[szmarczak]

whether I need to set a header when posting json or if that's automatic.

https://github.com/sindresorhus/got/blob/main/documentation/2-options.md#json

JSON body. If set, the content-type header defaults to application/json.

unable to find the basic documentation on the got object itself, such as the parameters for got.post()

Good one! I couldn't find it as well, so probably it's missing. Feel free to send a PR!

[ydarma]

Hi,

I started a quick start guide here https://github.com/ydarma/got/blob/quick-start/documentation/quickstart.md

Is it what you're looking for ? Please give some feedback and which topics could be added in your opinion ?

Thanks

[BryanDollery]

Hi,

I started a quick start guide here https://github.com/ydarma/got/blob/quick-start/documentation/quickstart.md

Is it what you're looking for ? Please give some feedback and which topics could be added in your opinion ?

Thanks

That's an excellent start! There are a few minor grammatical errors, but I don't think they impair comprehension, so it's probably best to ignore them.

One thing though, what do you think about separating out the parameters, to make it clear what parameter is used for what purpose, for those who have not read all the other docs (quickstart is usually read first, after all)? So, rather than:

const data = await got.post("https://httpbin.org/anything", {
  json: { documentName: "Quick Start" }
}).json();

You'd have:

const url = "https://httpbin.org/anything"; 
const options = { json: { documentName: "Quick Start" }}
const json= await got.post(url, options).json();

[ydarma]

Hi,

I followed your advice regarding extracting parameters to meaningful constants. This was a great advice :smile:.

I had a Miscellaneous section to give some useful pointers to the reader. I think that most applications only do GET, POST and error handling so the quick start can and should be short.

https://github.com/ydarma/got/blob/quick-start/documentation/quickstart.md

Regarding grammatical errors maybe a native English speaker will fix that in the future (help wanted 😄).

I'll make a pull request so we can continue the review in a more Github way...

[verhovsky]

#2059 is not the documentation I would like. It's definitely helpful and better than what was there before, but I wouldn't say it closes this issue. I am trying to learn what the got() API actually is in its entirety. The process to do that right now looks like this:

I google "got node documentation" and the first 4 results are 2 links to the README (npm then on GitHub) then 2 more links to the README that are fake and pretending to be links to docs. So I open the readme on GitHub.

I scroll past a bunch of ads and the first thing that looks like documentation is a link to this new quickstart guide (an improvement!) and click it. I see that the API is the classic got(url, optionsObject), I am curious about all the things that can be configured in that options object, since essentially what can and can't go in that object is the entire API of the library. The first thing I see that might direct me to that is the link to got.text in the quickstart, I click it and scroll up and I see documentation of the function I'm actually interested in. Next I click on the OptionsInit object which just brings me to that same object in a list of types? So I click on it again I guess, and that sends me to the source code, which looks like this

export type OptionsInit =
	Except<Partial<InternalsType>, 'hooks' | 'retry'>
	& {
		hooks?: Partial<Hooks>;
		retry?: Partial<RetryOptions>;
	};

First of all, I don't know what Except<Partial<>> does because I'm a typescript noob, but whatever, I can understand that InternalsType is what I'm interested in, so I look at what it means

export type InternalsType = Except<Options, OptionsToSkip>;

OptionsToSkip sounds like something I shouldn't care about, since they're skipped? So after like 7 clicks it looks like I just need to find where this Options type is defined... If I cmd+F for "type options" or "interface options" none of the results are that Options object. If I cmd+f for "options" in this file, there's 252 matches. The first mention of the Options object seems to be this line

export type InitHook = (init: OptionsInit, self: Options) => void;

which is not helpful. It seems like I need to clone this repo and open it in VS Code to get jump to definition or read the entire 2000 line file, but at this point I'd rather just go do something else, like write this rant :)

I eventually found the Options class right below that line scrolling around the file.

I would like a list of every option that can go in that object and what it does and any caveats relevant to using that option, like what axios has https://axios-http.com/docs/req_config I was able to use their library in a day or two https://github.com/curlconverter/curlconverter/pull/388 , but you want me to read the source just to use your library.

[szmarczak]

@verhovsky Thanks for the feedback, highly appreciated! You can scroll down in the readme to the Documentation section https://github.com/sindresorhus/got#documentation

There's an Options entry: https://github.com/sindresorhus/got/blob/main/documentation/2-options.md that explains how this class works in detail. It also includes all the important options.