geemus
HTTP API Design

Updated 7 months ago

burningman (@burningman) started discussion #4

3 years ago · 3 comments

Open

UUOC-X (Useless Use of Curl -X)

It's minor, but using -X in curl command lines is generally useless at best (except for DELETE or custom verbs), harmful at worst, see this post from the Daniel Stenberg (curl's main developer): https://daniel.haxx.se/blog/2015/09/11/unnecessary-use-of-curl-x/ It should be removed from a few pages in this book

Wesley Beary @geemus commented 3 years ago

Thanks for the heads up here, I was previously unaware of this. I'm a bit torn in that, though superfluous/useless technically, I wonder if they might help the examples be clearer and more human-readable.

Maybe it just suggests that examples more directly showing the request line (or something like it) would be clearer than using curl.

What do you think? I'd certainly like to use tools properly, but I also would hate for them to become weaker examples by being more ambiguous for others who (like me prior to your comment) are unaware of the implicit method changes in curl.

burningman @burningman commented 3 years ago

The "-d" flag could be replaced by one of its aliases, "--data" or "--data-ascii" (or even "--data-raw", if no "@file" is posted), to make it more readable that we're adding data to the request, which will then be POST, because what else in HTTP could we do with this extra data (given it's not the url, a header or a cookie)?

Maybe the request line could be given along with the example curl command-line to produce this very request line.

I wouldn't know which is best though.

Wesley Beary @geemus commented 3 years ago

I like your proposal to provide both the curl commands (with the fixes to make them more correct) and the request line. I think that makes it crystal clear and helps us provide correct curl usage. Would you be interested in helping with a pull request with those changes? Thanks!


to join this conversation on GitBook. Already have an account? Sign in to comment
Notifications

You’re not receiving notifications from this thread.


2 participants