Making API Requests Using cURL

Client for URLs, commonly known as cURL, is the name of a software project comprised of two development efforts—cURL and libcurl.

libcurl is a free, client-side URL transfer library with support for a wide range of protocols, including HTTPS. libcurl is portable, thread-safe, feature rich, and well suported on virtually any platform. It is probably the most popular C-based, multi-platform file transfer library in use.

cURL is a command-line tool for getting or sending files using URL syntax. Since cURL uses libcurl, it supports the same range of common Internet protocols that libcurl does.

This topic outlines the format and syntax used when making requests to the Phone.com API using cURL.

In This Topic:


Forming Requests Using cURL

Because our API is RESTful, cURL and libcurl are perfect tools to use when making requests to it. The following examples use cURL command-line syntax. The commands are easily translated into language-specific code using the libcurl library in that language.

For a basic HTTP GET against the /menus service:

Example:
curl -u App_key:App_pw --basic https://v1.api.phone.com/menus

cURL supports many useful options, most commonly you will need:

  • -X to specify the HTTP command (POST,PUT, DELETE)
  • -H to specify custom HTTP headers
  • -v for verbose output
  • -d to specify POST/PUT data (-d @file to use the contents of “file”)

We can first export a couple of shell environment variables to help keep track of our authentication strings. For example:

For Example:
export API_KEY="your api key"
export API_PASSWORD="your api password"

Now you will be able to use the cURL tool as follows: curl -u ${API_KEY}:${API_PASSWORD} --basic <url>

If you prefer to manually set your HTTP Basic authentication headers you can use the following syntax, instead of the above: curl -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh" <url>

Please note that two headers are always necessary for use with the Phone.com API:

For Example:
Content-Type: application/json
Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh

The Authorization header value is a concatenation of the string Basic with the Base64 representation of <API_KEY>:<API_PASSWORD>.

cURL Operations Template

Combining all of the above gives you a flexible template for making successful cURL requests on the command line:

HTTP GET Format


curl -X GET
 -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh"
 -H "Content-Type: application/json"
 https://v1.api.phone.com/<service>

HTTP POST Format


curl -X POST
 -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh"
 -H "Content-Type: application/json"
 -d '<JSON to post>'
 https://v1.api.phone.com/<service>

HTTP DELETE Format


curl -X DELETE
 -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh"
 -H "Content-Type: application/json"
 https://v1.api.phone.com/<service><resource_id>

Note that delete operations usually require that you specify a resource ID. Unless the delete_all query paramater is supported by the service and supplied. Please see the relevant API reference topics for more information.

Also note that if you don’t want to escape your JSON requests, you can use the -d flag with a real file:


curl -X POST
 -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh"
 -H "Content-Type: application/json"
 -d @json_request
 https://v1.api.phone.com/<service>
The code shown above will look for ~/json_request and post the contents to the Phone.com API.

cURL Code Examples

The code samples below show how you would use the templates above to post specific types of requests.

Sending an SMS


curl -X POST
 -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh"
 -H "Content-Type: application/json"
 -d '{"from": "+15555551234","to": "+15555551235","message": "Welcome to Phone.com"}'
 https://v1.api.phone.com/sms

Retrieving a List of SMS Messages for a Phone Number in Your Account


curl -X GET
 -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh"
 -H "Content-Type: application/json"
 https://v1.api.phone.com/sms

Deleting a Scheduled SMS Message


curl -X DELETE
 -H "Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh"
 -H "Content-Type: application/json"
 https://v1.api.phone.com/sms/0417048-ac3b-11e2-8b76-eea2f9d0a5a3

Learn More: