Get Started With the REST API

Setup PHP to make calls to the REST API

This guide explains how install and use PHP on your computer to interactively try out calls to the REST API. PHP is a programming language that is widely used for server-side code for web sites.

PHP provides high level libraries and language constructs that makes it suitable for learning and experimenting with the REST API. It is also suitable for development of production quality tools and systems.

Note that no web page or web server is needed for using PHP to make calls to the REST API. Instead, PHP is installed and invoked on the local machine from the command line in a terminal window.

1. Install PHP on a Local Machine

To check if PHP is already installed on the machine, open a terminal window and type:

php -v

If installed, this will print PHP version info.

If not installed, consult the PHP web site and the instructions for how to install PHP.

Below, a summary of how to install PHP on different operating systems is provided.

1.1. Install PHP on Windows

Download PHP for Windows here: windows.php.net/download/

Run the downloaded installer to install PHP.

1.2. Install PHP on macOS

Using homebrew (brew) is the recommended way to install PHP on macOS.

If homebrew is not installed, install it by following the instructions at brew.sh

When homebrew is installed, open a terminal window and run this command:

brew install php

1.3. Install PHP on Linux

Open a terminal window and run the following commands:

sudo apt update
sudo apt-get install php

2. Run PHP From the Command Line

There are two ways to run a PHP script from the command line:

Expicitly invoke the interpreter (works on all operating systems)
Call the script as a bash command (works on Linux and macOS)

2.1. Test the PHP Installation

Test the PHP installation by running this command in a terminal window:

php -v

Version information should be printed to the terminal.

2.2. Run Scripts Using the PHP Interpreter

This method works on all operating systems.

To run a PHP program as a script from the command line, specify the script filename like this:

php hi.php

In this example program, hi.php is a text file that contains the following code:

File: hi.php


<?php
echo "Hi World\n";

Note that to run a PHP source file as a script, the file must begin with <?php tag. It is recommended to omit the ending php tag in a PHP-only file.

2.3. Run Scripts as Bash Commands (Advanced Users)

This method works on Linux and macOS.

Instead of explicitly invoking the PHP interperter, a shebang interpreter directive can be placed on the first line of the script (also called “hash-bang”). The script can then be called directly on the command line.

To accomplish this, first add the shebang directive.

Insert the following line at the top of the PHP file (before the opening <?php tag):

#!/usr/bin/env php

For example:

File: hi.php


#!/usr/bin/env php
<?php
echo "Hi World\n";

Next, make the script runnable using the chmod command to add execution permissions. The following example sets the standard permissions for an executable file:

chmod 755 hi.php

The script can now be called without explicitly invoking the PHP interpreter.

The path to the PHP script needs to be specified when the command is invoked, unless the directory of the script is on the system PATH.

This command will run the script located in the current directory:

./hi.php

This command will run the script located in a subdirectory:

scripts/hi.php

It is possible to omit the .php extension from the file name.

The script can then be invoked like this:

./hi

The php command can still be used to run the script:

php hi

3. Using the cURL Library

To make HTTP requests in PHP, the cURL library is used.

3.1. Make a Get Request

Here is a basic code example that gets the content of a web page:

File: guide/get_started/request_webpage.php


<?php
/*
File: request_webpage.php

This example shows how to request a request_webpage.

Usage:

    php request_webpage.php
*/

// Function that makes an HTTP GET request
function make_request($url)
{
  // Create a cURL object from a URL
  $curl = curl_init($url);
  // Set option to return the response from the request as a string
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
  // Specify GET as the request method
  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
  // Include the response header so that it can be inspected
  curl_setopt($curl, CURLOPT_HEADER, true);
  // Execute the request
  $response = curl_exec($curl);
  // Return the response string
  return $response;
}

// Make request and print the result (includes the response header)
$response = make_request("https://riotsecure.io");
echo $response;

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

Call the above program as follows:

php guide/get_started/request_webpage.php

Output:

Terminal Window: Unauthorized call

3.2. Attempt to Call the REST API

In the following example, the code attempts to call the /auth route of the REST API without providing any authentication credentials. The code is the same as in the previous section, except for the URL, which is the address of the REST API demo server. This snippet calls the REST API:

Example


// Attempt to call the REST API without authorization header
$response = make_request("https://demo.riotsecure.io:6443/auth");
echo $response;

The above request should produce the following result:

HTTP/2 401
server: nginx/1.14.2
date: Tue, 25 Jan 2022 19:06:36 GMT
content-type: text/html; charset=UTF-8
content-length: 0
access-control-allow-credentials: true
access-control-allow-origin: *
access-control-allow-methods: POST, GET, PUT, DELETE, OPTIONS
access-control-allow-headers: Allow, Accept, Origin, Authorization, Content-type, Keep-Alive, User-Agent, Cache-Control, If-None-Match
access-control-expose-headers: WWW-Authenticate, ETag, Connection

Note that the request returns the HTTP code 401, which is the “Unauthorized” error code. The reason for this error is that no authentication information is provided with the request.

Source code:

File: guide/get_started/call_rest_api.php


<?php
/*
File: call_rest_api.php

This example shows how to make an unauthorized REST API call.

Usage:

    php call_rest_api.php
*/

// Function that makes an HTTP GET request
function make_request($url)
{
  // Create a cURL object from a URL
  $curl = curl_init($url);
  // Set option to return the response from the request as a string
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
  // Specify GET as the request method
  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
  // Include the response header so that it can be inspected
  curl_setopt($curl, CURLOPT_HEADER, true);
  // Execute the request
  $response = curl_exec($curl);
  // Return the response string
  return $response;
}

// Attempt to call the REST API without authorization
// HTTP error code 401 will be returned ("Unauthorized")
$response = make_request("https://demo.riotsecure.io:6443/auth");
echo $response;

// It is considered best practice to not close the <?php tag
// in a PHP-only file.

Example output:

Terminal Window: Unauthorized call

How authentication works is covered in detail in the Authentication Guide. Consult this guide to learn how to make authorized calls to the REST API.