request starts with http method might be more intuitive

[raeperd]

Hello @earthboundkid
I'm still using this module in production, and it works very well. Thanks for your great work again.

While creating numerous services using this module, I have encountered a few areas that I believe could be more intuitive. I highly respect the work that has gone into this project and would like to offer two suggestions that might enhance its usability without significant changes.

1. Building a request starting with the HTTP method.
2. Providing context.Context at the beginning of the request build process.

1. Building a Request Starting with the HTTP Method

Many HTTP client libraries support declaring the HTTP method early on, which is a natural choice given the nature of the HTTP protocol. GUIs like Postman also place the method at the top left, where the eye naturally goes first.

Currently, this module does not support simple way to support this approach. I believe a relatively simple modification could significantly enhance its intuitiveness. For example, it would be beneficial if the module could be used as follows. While the example uses only the GET method, similar support for POST, PATCH, DELETE, etc., would be greatly appreciated.

func main() {
	ctx := context.Background()
	var pokemon Pokemon
	
	// current. kinda verbose
	err := requests.New().Method("GET").BaseURL("https://pokeapi.co"). 
		Path("/api/v2/pokemon/ditto").
		Accept("application/json"). 
		ToJSON(&pokemon). 
		Fetch(ctx)


	// 1. starts with method?
	err = requests.Get().BaseURL("https://pokeapi.co").
		Path("/api/v2/pokemon/ditto").
		Accept("application/json").
		ToJSON(&pokemon).
		Fetch(ctx)

	// 2. starts with method and BaseURL
	err = requests.Get("https://pokeapi.co").
		Path("/api/v2/pokemon/ditto").
		Accept("application/json").
		ToJSON(&pokemon).
		Fetch(ctx)

	slog.Info("found pokemon", "abilities", pokemon.Abilities)
}

type Pokemon struct {
	Abilities []struct {
		Ability struct {
			Name string `json:"name"`
		} `json:"ability"`
	} `json:"abilities"`
}

2. Providing context.Context at the Beginning of the Request Build Process

This is another intuitive API modification. context.Context is mostly passed as the first parameter in function. Combined with the above modification, we could expect an API like the one below.

func main() {
	ctx := context.Background()
	var pokemon Pokemon

	// 3. starts with method and context and BaseURL
	err := requests.Get(ctx, "https://pokeapi.co").
		Path("/api/v2/pokemon/ditto").
		Accept("application/json").
		ToJSON(&pokemon).
		Fetch()

       // 4. ToJSON is effectively end of request building maybe?
	err = requests.Get(ctx, "https://pokeapi.co").
		Path("/api/v2/pokemon/ditto").
		Accept("application/json").
		ToJSON(&pokemon)

	slog.Info("found pokemon", "abilities", pokemon.Abilities)
}

Looking at the code, I couldn't find any internal reason why such an API would be impossible(But context at last thing is kinda breaking changes...)

If you lack the time, I am willing to make the related modifications and create a pull request.
What do you think about this new API?

[earthboundkid]

Thanks for your interest in this module.

This would be a major change to the API and the basic concepts behind how it works. In particular, one thing I really like about the current system is that you don't have to specify the method 99% of the time because it can infer GET or POST from whether you have a request body or not. Setting the method is only necessary when you want to use POST without a body, DELETE, PATCH, or other uncommon methods. This is similar to curl, which also infers GET/POST/HEAD from the kind of request you make.

Conceptually, request.Builder has three phases: it builds a URL, it builds a request, it sends the request and handles the response. Context only comes in at the second phase. In particular, I like to use requests to make API clients where the URL is partly or totally filled out at init time and then individual requests fill in the context and handle the response. Requiring a context early on wouldn't be compatible with this.

I think if you're interested in exploring other ideas for the API, your best bet is to fork the repo and make something for yourself. Honestly, even though I've put a lot of time into this, requests isn't actually a lot of code. Most of the work is in testing and documentation, filling out all possible options, etc. I started out with just a single function as an HTTP helper and only made requests as a package when I came up with a generalized design that I thought I could use in more situations. If you prefer something that looks more like Python's requests.get(url), you're probably better off just writing your own helper function and then letting it evolve over time and seeing how it grows.

[raeperd]

Thank you for your quick and thoughtful response.
Given your suggestions, I will fork the repo and create a helper function tailored to my needs.