Charles Engelke's Blog

A lot of what I do lately involves creating or consuming RESTful web services.  (By the way, Leonard Richardson‘s and Sam Ruby‘s book by that name is fantastic.)  One really nice thing about RESTful services is that you can do many of the operations with a simple web browser.  But not all: web browsers are happy to do GET requests and, with a little effort, POST requests, but none of the other HTTP verbs.  If you’re trying to do anything significant with a RESTful web service, sooner or later you’re going to need to perform PUT, DELETE, and HEAD requests, too.

That’s where curl comes in.  It’s an open source command line tool that can perform just about any kind of HTTP request operation.  It certainly can do everything I ever need to try in testing a RESTful web service.  But every time I use it I have to look at the help page for it, which is incredibly long, because I can’t remember all the command line switches I need.  So I’m writing up a cheat sheet here, with the switches I need to use.

The basic form of a curl command is curl -X verb [options] uri, as in:

   curl -X GET -D headers.txt http://example.com/some/path

The command above will perform an HTTP GET request for the URI http://example.com/some/path.  It will store the response headers in the file headers.txt (that’s what the -D headers.txt option makes happen) and will send the actual response body to standard output.  You can redirect standard output to a file if you want to save the response, or if it’s not simple text (for example, if you want to GET a photograph).

The HTTP verbs that I use with curl are GET, PUT, POST, DELETE, and HEAD.  The command options that I use most often are:

-D filename

Save the response headers in the file filename.

-i

Send the response headers to standard output, along with the response body.

–basic –user username:password

(There are two hyphens each before basic and before user.)  Authenticate the request with HTTP Basic authentication, with the specified username and password.

-H “header: value“

Set a request header named header to the specified value. Note the double quotes, which causes your command shell to pass the entire header specification to curl as a single string.  You can specify multiple -H options to set multiple request headers.

-T filename

Send the contents of the specified file as the body of a PUT request. Useful for uploading files.

-k

Ignore SSL certificate problems. Very useful when talking to a development server with a self-signed certificate. Otherwise curl will refuse to connect to it.

-h

For help. Show all the possible command line options.

There are a bunch of other switches, but these are the ones I use all the time. You may need some others. For example, if you use web services that expect form data via HTTP POST, you’ll want to learn about the -F option.

Cory Doctorow put up a glowing post about Lenovo’s ThinkPad warranty service yesterday.  I’m not surprised.  His experience is similar to the ones I’ve had with ThinkPad service over many years.  And, as it happened, I was using ThinkPad warranty service when I saw his post.

Unlike Cory, I didn’t pay for on-site service, just regular “depot” service.  But they still did great.  My ThinkPad just went dead Tuesday evening.  In more than 15 years of using them, I’ve never had a similar problem before.  But I phoned them up to get it fixed.  They actually listened to my description of the diagnostics I’d already performed, believed that I was describing them accurately, then spent about three more minutes having me answer a couple of questions and trying one more thing.  They diagnosed the problem as a bad system board needing replacement, and said they’d send me a box to ship the unit in.

This was Tuesday evening.  Wednesday morning, the empty box arrived.  I put my ThinkPad (without the hard drive) in it and called UPS to get it.  They picked it up that afternoon.  Thursday morning the Lenovo website said my unit was being repaired, and Thursday afternoon, that it had been fixed and shipped back to me.  Friday morning I waited for our receptionist to tell me that UPS had delivered it.

That service turnaround speed is fantastic!  Or, it would have been, if my PC had ever shown up.  I called the ThinkPad support line and they tracked the UPS package and found that an “exception” had occurred.  I looked it up myself.  Here’s what it said:

THE RECEIVER IS ON VACATION. DELIVERY WILL BE ATTEMPTED WHEN THE RECEIVER RETURNS

I’m on vacation?  Shouldn’t I know about that?  Why am I in the office, then?

I checked with our receptionist, who said that UPS had shown up early today but didn’t have any packages to drop off.  UPS and Lenovo agreed that the address label had the right address on it, except that the zip code was off by one (which is still in the same town).  UPS said they’d already fixed that zip code.  So what happened that led to that exception?

What didn’t happen was what they claimed in the tracking log: that they tried to deliver the package to the correct address only to be told that I was on vacation!  My guess is that the driver may have put the package in the wrong part of the truck (due to the zip code) and discovered it after he’d already visited our business.  And then put that stuff about a “vacation” down as an excuse for not having delivered it on time.  This isn’t the first time I’ve had UPS miss a delivery date and put down some completely bogus reason in the tracking log.  It may be the driver doing it, it may be someone in a back office.  But there definitely are UPS staffers who make up false reasons when they don’t make a delivery they should.

UPS refused to make it right by getting the package to me today like they should.  Instead, I can wait until Monday and go without my PC a few more days, or drive over a hundred blocks to their facility in the boondocks to get it myself.  I’ll probably do that, but I’m not happy about the wasted time and money on my part.  UPS is doing nothing at all to make it right.

As I said above, this kind of thing has happened to me before with UPS, maybe about one time out of every twenty or thirty deliveries.  That’s not a big percentage, but it’s a lot higher failure rate than I’ve had with FedEx.  I’ll never use UPS when I have a choice, and I’ve already made a complaint with Lenovo suggesting that they should reconsider using UPS, too.