Examples don't jive with the actual middleware stack order about her HOT 4 CLOSED

You’re right, builder.use does not work for that case. I’ll update the documentation. But I agree that builder.insert(0, MyAuthentication) is not pretty. However, I submitted this pull request for Faraday a few hours ago. We’ll see how it will play.

The simplest solution would be for Her to not include any default middleware. When setting up Her::API, the user would have to include all the needed middleware:

Her::API.setup :base_uri => "https://api.example.com" do |builder|
  builder.use FaradayMiddle::OAuth
  builder.use Her::Middleware::FirstLevelParseJSON
  builder.use Faraday::Request::UrlEncoded
  builder.use Faraday::Adapter::NetHttp
end

It would require more work for developers, but it would give them more control. What do you think?

from her.

I decided to drop all default middleware and to let the user define the entire stack. I’m closing the issue as the documentation is now accurate :) Thanks!

from her.

FWIW, I think there's still use in allowing sensible defaults instead of requiring the stack to be configured every time. When I get some more time, I'm going to play around with it and hopefully come up with something that makes it easy to configure the stack without engineering something crazy.

from her.

Cool, let me know when you have something working.

At first I thought it would be a pain to require the entire stack each time you need to initialize the API, but for the developer it’s a one-time thing. The block is in config/initializers/her.rb or something similar and is never touched again.

from her.