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.
- 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.
- 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.
- 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.