PHP Consuming RESTful APIs Introduction

Consuming RESTful APIs

Introduction

When you want to find out the weather forecast for New York City, the latest tweets from @rasmus, or update a stored file, you can write a short REST script to process that data in a format you can easily manipulate.

REST is a straightforward style of web APIs in which you make requests to a URL using HTTP methods, such as GET and POST. The URL and body, often in JSON or XML, describes the resource you want to manipulate and the method tells the server what action it should take.

GET tells the server you want to retrieve existing data, whereas POST means you want to add a new resource. Use PUT to replace a resource or create a specifically named resource. And DELETE, of course, deletes the resource.

The brilliance of REST is in use of existing standards. Because most developers are familiar with HTTP and JSON, the learning curve for REST is short and shallow. The one downside to REST is there’s no standard schema for data that’s passed in or returned. Every site is free to use what it feels is the best. 

Though this is not a problem for small services, if not designed properly, this can cause complexity when a service grows. Still, REST is a very popular format and its simplicity is a key factor in its success. Covers making REST requests.

Recipes in this chapter cover how to generate an HTTP request for your desired REST call. Because the data returned is (almost always) in a standard file format, there’s no need to show how to parse the results. Given the nature of REST documents, and that you’re usually familiar with the schema of the response, the JSON and SimpleXML extensions are often the best choice.

There are many ways to retrieve a remote URL in PHP. Choosing one method over another depends on your needs for simplicity, control, and portability. The three methods discussed in this chapter are standard file functions, the cURL extension, and the HTTP_Request2 class from PEAR. These three methods can generally do everything you need and at least one of them should be available to you whatever your server configuration or ability to install custom extensions. Other ways to retrieve remote URLs include the pecl_http extension, which, though still in development, offers some promising features, and using the fsockopen() function to open a socket over which you send an HTTP request that you construct piece by piece.

Using a standard file function such as file_get_contents() is simple and convenient. It automatically follows redirects, so if you use this function to retrieve the directory at http://www.example.com/people and the server redirects you to http://www.example.com/people/, you’ll get the contents of the directory index page, not a message telling you that the URL has moved. Standard file functions also work with both HTTP and FTP. The downside to this method is that it requires the allow_url_fopen configuration directive to be turned on.

The cURL extension is a powerful jack-of-all-request-trades. It relies on the popular libcurl to provide a fast, configurable mechanism for handling a wide variety of net‐work requests. If this extension is available on your server, we recommend you use it.

If allow_url_fopen is turned off and cURL is not available, the PEAR HTTP_Request2 module saves the day. Like all PEAR modules, it’s plain PHP, so if you can save a PHP file on your server, you can use it. HTTP_Request2 supports just about anything you’d like to do when requesting a remote URL, including modifying request headers and body, using an arbitrary method, and retrieving response headers.

Explain how to make various kinds of HTTP requests, tweaking headers, method, body, and timing. Helps you go behind the scenes of an HTTP request to examine the headers in a request and response. If a request you’re making from a program isn’t giving you the results you’re looking for, examining the headers often provides clues as to what’s wrong.