curl intro and installation | Documenting APIs
I’d Rather Be Writing
Learn API Doc
Using an API like a developer
Last updated: Jan 01, 2019
While Postman is convenient, it’s hard to use it 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 use curl.
About curl
Installing curl
Install curl on Mac
Install curl on Windows
Make a test API call
Notes about using curl with Windows
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.
Sometimes curl is written as cURL. It stands for Client URL. “curl” is the more common convention for its spelling, but both refer to the same thing.
curl is usually available by default on Macs but requires some installation on Windows. Follow these instructions for installing curl:
If you have a Mac, by default, curl is probably already installed. To check:
Open Terminal (press Cmd + spacebar to open Stoplight, 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. 0 SecureTransport zlib/1. 2. 8
Protocols: dict file ftp ftps gopher 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.
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 choose the With Administrator Privileges (free) installer.
After you install curl, test your version of curl by doing the following:
Open a command prompt by clicking the Start button and typing cmd.
Type curl -V.
The response should be as follows:
curl 7. 0 (x86_64-apple-darwin14. 37. 1 SecureTransport zlib/1. 5
Protocols: dict file ftp ftps gopher imap imaps ldap ldaps pop3 pop3s rtsp smtp smtps telnet tftp
Features: AsynchDNS GSS-Negotiate IPv6 Largefile NTLM NTLM_WB SSL libz
After you have curl installed, make a test API call:
curl -X GET ”
(In the above code, replace APIKEY with your actual API key. )
You should get minified JSON response back like this:
{“coord”:{“lon”:-121. 96, “lat”:37. 35}, “weather”:[{“id”:701, “main”:”Mist”, “description”:”mist”, “icon”:”50d”}], “base”:”stations”, “main”:{“temp”:66. 92, “pressure”:1017, “humidity”:50, “temp_min”:53. 6, “temp_max”:75. 2}, “visibility”:16093, “wind”:{“speed”:10. 29, “deg”:300}, “clouds”:{“all”:75}, “dt”:1522526400, “sys”:{“type”:1, “id”:479, “message”:0. 0051, “country”:”US”, “sunrise”:1522504404, “sunset”:1522549829}, “id”:420006397, “name”:”Santa Clara”, “cod”:200}
In Windows, Ctrl+ V doesn’t work; instead, you right-click and then select Paste.
If you’re using Windows, note the following formatting requirements when using curl:
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 -k in the curl command, you can bypass curl’s security certificate, which may or may not be necessary.
24/159 pages complete. Only 135 more pages to go.
Installing and using cURL | Zendesk Developer Docs
All the examples in the Zendesk REST API docs use cURL, a lightweight, command-line tool for making HTTP requests without a web browser. cURL lets you try out various API requests in a command-line interface such as the command prompt in Windows or Terminal in macOS. You don’t need to build a working web application just to try out the APIs.
cURL makes HTTP requests just like a web browser. To request a web page from the command line, type curl followed by the site’s URL:
The web server’s response is displayed directly in your command-line interface. If you requested an HTML page, you get the page source — which is what a browser normally sees.
Related topic
cURL documentation
Disclaimer: Zendesk can’t provide support for third-party technologies such as cURL or Windows. Please post any issues in the comments section or search for solutions online.
Using cURL
You can use cURL to inspect and test different Zendesk API requests without having to build a functioning web application. For example, the following cURL statement makes an HTTP request to the List Groups endpoint in the Zendesk API:
curl \ -v -u [email protected]:mypassword
The API returns a JSON object that lists the groups in your Zendesk Support instance:
{ “groups”: [ { “name”: “DJs”, “created_at”: “2009-05-13T00:07:08Z”, “updated_at”: “2011-07-22T00:11:12Z”, “id”: 211}, { “name”: “MCs”, “created_at”: “2009-08-26T00:07:08Z”, “updated_at”: “2010-05-13T00:07:08Z”, “id”: 122}]}
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It’s designed to be easy for humans to read and write, and for machines to parse and generate. To learn more, see Working with JSON.
Using cURL in Windows
You can use the Windows command prompt to run the cURL examples. To start the command prompt, open the Start menu, type cmd in the search box, and press Enter.
Note: Windows 10 users can install and use a Bash shell, a Unix command-line interface that’s the same as the one in macOS. See Setting up a Bash shell in Windows 10 in this Help Center. If you use this option, ignore all the instructions for Windows users in this article.
cURL isn’t installed in Windows by default. See Installing cURL below to install it on your system.
The examples in the docs have to be modified slightly to work correctly in Windows. First, replace any line-ending backslash (\) character with the caret (^) character. Second, if an example contains JSON data, move the data to a file before running the example. The following sections give more details.
Replace line-ending backslashes
The cURL examples often have a backslash (\) at the end of lines to break up a long statement into easier-to-read lines. The backslash is a line continuation character in UNIX but not in Windows. In Windows, replace any backslash at the end of lines with the caret (^) character, which is an escape character in Windows. Don’t leave any space after any ^ character or it won’t work. The caret will escape the space instead of the new line.
Example:
curl ^ -v -u [email protected]:mypassword
You can paste a multiline statement at the command prompt by clicking the icon in the upper-left corner and selecting Edit > Paste. If you prefer using the keyboard, press Alt+spacebar to open the menu, then press E and P.
Move JSON data to a file
The Windows command prompt doesn’t support single quotes. It’s a problem because cURL statements use single quotes to specify JSON data. Example:
curl {subdomain}. ^ -d ‘{“group”: {“name”: “My Group”}}’ ^ -H “Content-Type: application/json” ^ -v -u {email_address}:{password} -X POST
The statement specifies JSON data for creating a group (the -d flag stands for data). Because the JSON is enclosed in single quotes, the statement won’t work on the command line.
To fix the problem, save the JSON in a separate file and import it into the cURL statement. To modify the example above, create a file named containing the following text:
{“group”: {“name”: “My Group”}}
Next, change the cURL statement to import the JSON data with the @filename syntax:
curl {subdomain}. ^ -d ^ -H “Content-Type: application/json” ^ -v -u {email_address}:{password} -X POST
Before running the statement, use the cd command (for change directory) to navigate to the folder that contains the file. Example:
C:\> cd json_files
Then paste the cURL statement at the command prompt:
An alternative to moving the JSON to a separate file is to use double quotes around the JSON data in the cURL statement and escape the inner ones with backslashes:
-d “{\”group\””: {\””name\””: \””My Group\””}}”” \
