Making a REST Request

Making a request to our API is easy! API requests are simply REST requests, which are HTTP requests formatted in a specific way.

You can make a REST request in one of three ways:

  • Using your web browser
  • Using a web-based browser extension or other third-party tool
  • Using your programming language of choice

Most programming languages provide a high-level interface to make HTTP requests, either through their SDKs or through one or more third-party libraries.

HTTP Headers and Parameters

The Phone.com API relies on the HTTP protocol to specify parameters for your REST requests. A request’s format and encoding can be specified using standard HTTP headers. With the exception of authentication credentials (your application’s API key and password), most settings can also be provided as URL parameters if your library doesn’t make it easy to modify HTTP headers.

Making a Request Using Your Web Browser

You can send requests to the Phone.com API using your browser’s Location bar. Simply type the URI for a Phone.com API resource.

Example:
POST https://v1.api.phone.com/menus

Your browser will ask you to provide your username (API key) and password (API password), and will display a JSON document listing the menus currently set up in your Phone.com account.

Note that making a REST request using your browser does not support HTTP methods include a document to be sent to the API as part of the request, as in the case of POST or PUT.

Making a Request Using a Browser Extension

Most modern browsers support third-party extensions that can be use to build REST requests using a graphical user interface. These tools let you set a specific HTTP method, customize headers and then pass a document to the server.

We like Chrome’s REST Console, but there are good REST clients for Firefox, Opera and Internet Explorer also.

Making a Request Using cURL or libcurl

cURL is a command-line tool that is pre-installed on most operating systems. You can also download it on the cURL website. After installing cURL, use your operating system’s shell to type a command as follows: curl -u App_key:App_pw - -basic <URL>

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

cUrL supports many useful options:

  • -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”)

For more information on using cURL on the command line see REST-esting with cURL.

libcurl is a C library that provides the functionality of the cURL command line for C. Bindings also exist for many other languages.

Making a REST Request Using PHP

A common way to make a REST request is using the libcurl library for PHP. When making a request to the Phone.com API, you will need to include the following components:

Initialize the Request


  $curl = curl_init();


Define the URL


  curl_setopt($ch, CURLOPT_URL, "https://v1.api.phone.com/menus");

Note that all requests must be sent using SSL (HTTPS protocol). You cannot access the Phone.com API using plain HTTP.


Authenticate the Request


  curl_setopt($ch, CURLOPT_USERPWD, $app_key.':'.$api_pw);


State the Request Method

Set options for each HTTP method as shown below:

POST


  curl_setopt($ch,CURLOPT_POST,true);

PUT


  curl_setopt($ch,CURLOPT_PUT,true);


DELETE


  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");


Include POST or PUT Data

To include an HTTP request body (for POST and PUT requests only):


  curl_setopt($ch, CURLOPT_POSTFIELDS, "[HTTP body]");


Enable Verbose Mode

If your request fails, try repeating it, with verbose mode enabled. Doing so will write diagnostic information about the execution of your command to STDERR, which allows you to see any errors that have occurred. Note that in most webserver configurations, these errors will be sent to the main webserver error log (for example: /var/log/apache2/error.log).


 CURLOPT_POSTFIELDS => CURLOPT_VERBOSE


Execute the Request

To complete and execute the request:


  $result=curl_exec ($ch);
  curl_close ($ch);


Learn More: