curl intro and installation
While Postman is convenient, it’s hard to represent how to make calls with it in your documentation. Additionally, different users probably use different GUI clients, or none at all (preferring the command line instead).
Instead of describing how to make REST calls using a GUI client like Postman, the most conventional method for documenting request syntax is to explain how to make the calls using curl.
- About curl
- Installing curl
- Make a test API call
curl is a command-line utility that lets you execute HTTP requests with different parameters and methods. Instead of going to web resources in a browser’s address bar, you can use the command line to get these same resources, retrieved as text.
curl is usually available by default on Macs but requires some installation on Windows. Follow these instructions for installing curl:
Install curl on Mac
If you have a Mac, by default, curl is probably already installed. To check:
- Open Terminal (press Cmd + space bar to open Spotlight, and then type “Terminal”).
In Terminal type
curl -V. The response should look something like this:
curl 7.54.0 (x86_64-apple-darwin16.0) libcurl/7.54.0 SecureTransport zlib/1.2.8 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz UnixSockets
If you don’t see this, you need to download and install curl.
Install curl on Windows
Installing curl on Windows involves a few more steps. First, determine whether you have 32-bit or 64-bit Windows by right-clicking Computer and selecting Properties. Then follow the instructions in this Confused by Code page. Most likely, you’ll want to select the With Administrator Privileges (free) installer.
After it’s installed, test your version of curl by doing the following:
- Open a command prompt by clicking the Start button and typing cmd.
The response should be as follows:
curl 7.54.0 (x86_64-apple-darwin14.0) libcurl/7.37.1 SecureTransport zlib/1.2.5 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smtp smtps telnet tftp Features: AsynchDNS GSS-Negotiate IPv6 Largefile NTLM NTLM_WB SSL libz
Make a test API call
After you have curl installed, make a test API call:
curl -X GET "http://api.openweathermap.org/data/2.5/weather?zip=95050%2Cus&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"
You should get minified JSON response back like this:
In Windows, Ctrl+ V doesn’t work; instead, you right-click and then select Paste.
If you’re on Windows 8.1 and you encounter an error that says, “The program can’t start because MSVCR100.dll is missing from your computer,” see this article and install the suggested package.
Notes about using curl with Windows
- Use double quotes in the Windows command line. (Windows doesn’t support single quotes.)
- Don’t use backslashes (
\) to separate lines. (This is for readability only and doesn’t affect the call on Macs.)
- By adding
-kin the curl command, you can bypass curl’s security certificate, which may or may not be necessary.
13/94 pages complete. Only 81 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.