doc suggestions

[gurgeous]

(see #1168) I think the current docs are great, but might benefit from a few improvements:

1. Show method signatures for get/post/etc. Easy change, big benefit IMO.
2. JSON. Took me a long time to find :json and figure out how to make it work. The docs could give some hints about that.
3. Explain default_connection and show how :url_encoded is in the default middleware stack.
4. Explanation for the middleware difference between #use, #request & #response. Still not totally sure I understand. This is just a namespacing thing, right?
5. Move away from sushi.com for examples. Perhaps google, httpbingo, hacker news, youtube, wikipedia, etc? No preference, open to suggestions.

What do you guys think?

[iMacTia]

Thanks @gurgeous, this feedback is incredibly useful and I understand all the point above can be source of confusion for new developers.

1. That makes sense!
2. Agree, I often see developers manually encoding the body and setting the Content-Type header, we should definitely increase awareness around faraday_middleware. At the same time, we're currently planning on tearing that repo apart in favour of single-middleware repos 😄! So maybe we could take this opportunity to create a faraday-json gem first and advertise that in the docs? (cc @olleolleolle)
3. This is the only point where I have a few reservations, but it's a long topic so I'll drop them after this list, see below.
4. Another source of confusion, I agree! And you're right, it's simply namespacing, or "buckets" in which you can register a middleware. You can always use #use and it will work regardless of the middleware. Same goes for the middleware registration, it's just a shorthand, you can always add a middleware by calling #use on its class without having to register it. This is another thing we're considering to drop in v2.0 as it could potentially cause clashes between middleware (e.g. 2 gemified middleware choose the same name).
5. I checked out and really liked https://httpbin.org after your mentioned it, totally agree to have working examples 👍 !

On the utility methods and the default_connection

One thing I'd like to point out is that the "utility methods" exposed by the main Faraday module (get, post, and so on...) are supposed to be shortcuts but are not the recommended way to use faraday.
Same goes for the default_connection one should be very careful about using it and the reason is that it only works in simple projects with no dependencies using Faraday explicitly.
In case of a bigger project using different gems based on Faraday and calling multiple APIs, it would be very simple to cause conflicts because there would be one default_connection for everyone.

So a much better approach is to instead create one connection object per API and then use that instead to configure how the communication with that API should work.

[iMacTia]

Awesome, thanks @gurgeous!
I think the shortcut methods are very "catchy" and allow new developers to use faraday with a single line of code, potentially getting their interested, so it's not like I'm against them at all.
The problem though is when they become THE way to use Faraday 😅.

If we could find a way to keep them while also highlighting the connection as "the way to go", then that would be fine to me, otherwise I don't think they would be a huge loss 😄. I'm honestly thinking about dropping them in v2 regardless (but this is still my personal opinion, I haven't discussed this with the team)

Thanks again for helping out with this! I look forward to a PR.
Also, no need to make ALL changes in a single PR, feel free to break it down into multiple PRs 👍!
It might be easier for you to fit in your schedule, and quicker for us to review 😃

[gurgeous]

First snag... I wanted to use http://httpbingo.org in the Usage samples, but it's confusing. You end up with code like:

resp = Faraday.get 'http://httpbingo.org/get'

which just doesn't look great. Unless you object, I will switch to google.com or maybe github.com instead:

resp = Faraday.get 'https://www.google.com'
# or
resp = Faraday.get 'https://api.github.com/users/iMacTia'

[iMacTia]

Sure! Google looks fine and we know it will always be there 😄!

[iMacTia]

Also, you can probably just Faraday.get 'http://httpbingo.org' as that should return the homepage?
So if you later use httpbingo for other, more complex examples, at least it stays consistent

[gurgeous]

OK, maybe I'm just overanalyzing. Let's try httpbingo.org and see how it feels. I love that thing and use it all the time, might as well spread the word.

[gurgeous]

Thanks for your help with the usage page. Very pleased with the new content. I'd be happy to work on the Middleware page too. Some ideas:

1. List more middleware. Specifically thinking of cookie_jar, encoding, http-cache, etc. Any other important middleware we should list? https://rubygems.org/search?query=faraday. Perhaps a table?
2. Actually I think maybe the Available Middleware content should move onto the middleware page. This is a huge selling point for Faraday. Maybe the most important feature. Let's put it front and center! 😄
3. use vs request vs response
4. Touch on a few things from the new usage page - unlocking the power of faraday via middleware, the default stack, etc.

[iMacTia]

@gurgeous I'm actually working on a new repository altogether to collect and categorise faraday middleware gems to make it easier to discover them: awesome-faraday (similar to the "awesome-*" projects that are now quite popular).

Adapters are already there, next will be middleware. Considering the fact that there are plenty, we could fill that repo with a comprehensive list and just point to it from the website? We can then use the website to document how middleware work (I recently had to explain why response middleware are traversed in reversed order) and how you can write your own.

So I totally agree with your point 3 and 4, we should definitely try to make it clearer, but I'd delegate to awesome-faraday for the comprehensive list of middleware

[gurgeous]

I like the idea of a separate repo for the middleware list, good idea. Maybe we limit the Middleware page to just the most important stuff.

I think there is a (minor) issue with people expecting Faraday to do more out of the box, and we can help alleviate that pain with some quick suggestions. Something like :url_encoded, :encoding, :retry, :json, :follow_redirects...

Happy to help with the awesome-faraday repo too...

[gurgeous]

OK, I think my original goals have been met. Thanks guys. Happy to contribute more docs if anyone has suggestions.

The only other thing I'd perhaps like to see is a hint about how to dump the current middleware stack. I've gotten some mileage out of rake middleware. Almost wish we had Faraday::Connection#middleware_stack or something as a shortcut.

puts f.builder.handlers.map(&:klass)

[olleolleolle]

When you say "dump" you mean perhaps"print the currently configured stack for visual inspection", as opposed to "delete it and replace it with something else"?

[gurgeous]

Yes - I am talking about printing for visual inspection

[trdrdriror]

I am new to Ruby so please be gentle. First off, I really like Faraday so far it has been simple to use and the design/codebase has been educational. Second, I am wondering about the documentation regarding the main http functions (delete, get, head, post, put trace) in the Connection class. Those are listed in the document as Class Method's but their usage seems to be as Instance Methods (see example at the top of that doc page). You use the class_eval method which, according to https://web.stanford.edu/~ouster/cgi-bin/cs142-winter15/classEval.php, indcates that class_eval "...define[s] an instance method (one that applies to all of the instances of ClassName)" vs instance_eval which "...define[s] a class method (one associated with the class object but not visible to instances)." Given my limited experience I am sure I am missing something but just in case I thought I would post info here.

[olleolleolle]

There are "convenience methods" on the Faraday class, such as Faraday.get. These get created with some sleight of hand metaprogramming. Could that be one of the clues?

[iMacTia]

I think @trdrdriror is right here, I just checked the RubyDoc for Faraday::Connection and it shows them as class methods.
That is obviously not true, as they're instance methods on Connection and class methods on Faraday.
I suspect the cause is the @!scope class decorator on the doc for those methods.

Good catch @trdrdriror, don't be afraid of speaking up just because you're new to Ruby 👍!
Would you like to open a PR to get the documentation fixed? It should be a simple one if you'd like to give it a try

[iMacTia]

And FYI -- the sleight of hand @olleolleolle referred to is this one: https://github.com/lostisland/faraday/blob/main/lib/faraday.rb#L143-L150. If you call the Faraday.get class method (or any other HTTP method), that will in turn instantiate a new default_connection object (i.e. Faraday::Connection) and call the #get instance method on it.
I jsu checked RubyDoc and these class methods are not present, which is unsurprising since they don't actually exist in the code, they're proxied by method_missing

[trdrdriror]

@iMacTia Thanks for getting back to me. Yes I would like to try the PR if you don't mind potentially waiting a couple days as I am traveling and on client site for next few days.

[iMacTia]

Absolutely! This is not corporate work, this is OSS contributions. Take the time you need and thank you in advance for raising and fixing this 🙏