Consume an API in PHP

Getting started

Every API can be consumed with a PHP client library, that is a wrapper around the JSON API.
The PHP client library is always made of two parts:

• A mashape folder, that contains the core functionalities of every PHP client library and that is immutable for every component.
• An auto-generated *.php file targeted for the specific API, that has "nearly" the same name of the API.

The client library automatically constructs the "X-Mashape-Authorization" header for every request, and deserializes the response into ready to use PHP objects.

Initialize the library

To use the client library, include the auto-generated *.php file (located in the root directory) in your code. Then, initialize a new PHP client object, whose class is defined in the auto-generated *.php file and has the same name of the *.php file. The constructor accepts two arguments, that are your Public and Private keys.

For example, if you download the Bitly API's PHP client library, you will get the following files:

|- mashape - The base PHP client folder.
|- Bitly.php - The auto-generated *.php file for the API, that declares a Bitly class.
|- LICENSE
|- README

To initialize the client library instantiate a new Bitly object setting your Public and Private keys in the constructor. For example:

Call a method

The client object exposes all the methods available for the API, that you can easily call. The methods may require some arguments (some of them may be optional), according to the API's documentation.

The execution of a method may throw a MashapeClientException when a fatal error occurs and the request failed (for example when the keys are not valid). A fatal error is different from a generic error, it means that the HTTP request wasn't successful for the following reasons:

• You have provided invalid credential keys.
• No or invalid response by the API.

You can handle the exception with its code and message value, go to the errors section for more info.

For example, a sample client implementation for the Bitly API could be:

Read the response

Every method returns an object that wraps the JSON response that has the same structure like described in the API's documentation.

Handle the response according to the component's documentation. Remember that the response is an object.

Errors

Like the JSON API, there may be API's custom API or Mashape errors. See the errors section for more info.

Update the client library

It may happen we release a new version of the client library. It's a good practice to update your API's client library installations when a new version is available.

To update the library, delete the mashape folder and replace it with the new one. Your implementation should keep working as usual.

If you are consuming more than one API with the client library, a tip could be to keep just one installation of the library (one mashapebase folder) and move only the auto-generated *.php file for the new components you want to consume into the existing installation. In this way when you will have to update the client library to a newer version, replacing just one folder is all that's required.