Documentation Get Support

Consume an API in PHP

This PHP library has been deprecated in favor of our new opensource Unirest library. Check out the PHP docs here: Unirest.io/?language=PHP

Installation & Dependencies

Using the Mashape PHP client library is as simple as dropping the unzipped contents of the downloaded library into your project. Only one copy of the mashape/ folder is needed for all the {API_name}.php files you use in your project.

The Mashape library depends on libcurl to make HTTP requests. Many installations of PHP have cURL installed by default. The following code snippet will determine if libcurl is installed on your server:

If no exception is thrown, libcurl is properly configured. If an exception is thrown, follow these installation instructions.

Consume an endpoint

When you download a PHP client library, you will always find two files: a sample file that allows you to get started immediately, and another file named after the API.

To authenticate your client application with Mashape, it is required to provide a Mashape Test Key. There are two different kind of keys:

Testing: This key should be used only for testing purposes because it has unlimited access to every API.

Production: Create a new restricted key every time you need to use an API in production. These keys can access only the APIs that you specify.

Keys should be kept secret and never shared with anyone!

Read the response

The client library returns a MashapeResponse object that includes the response of the endpoint. It has the following properties:

  • int code: the HTTP status code.
  • array headers: the response headers.
  • string rawBody: the non-parsed raw body.
  • (stdClass, string) body: the parsed body.
    • It's a string when the API returns a binary response.
    • It's a stdClass when the API returns a JSON object or plain string response.

For example, the george-vustrey/weather API returns an array of weather conditions, as you can read from the documentation:


[{
    "condition": "\"Partly Cloudy\"",
    "day_of_week": "Mon",
    "high": 79,
    "low": 60
}]

To find out the condition of the day's weather, we would then write:

Authenticating with OAuth

When an API is protected by OAuth 1.0a or OAuth 2.0 you need to take four additional steps before starting to consume the endpoints:

Properly configure the Callback URL property in the third party service settings.
Redirect the user to an auto-generated URL that we generate, and that will allow him to grant permissions to your app.
The user will be redirected back to your app where you can parse the OAuth Tokens.
Authorize the app against the API with the OAuth Tokens.

In the real-world if the API is protected by OAuth 1.0a, every request must submit a special OAuth signature. On Mashape instead it's easier to consume OAuth 1.0a because no signature is required on your side: we automatically sign requests in background.

Configure the Callback URL

Some services, like Twitter, GitHub or Facebook, require that you to specify a property called Callback URL in your Application settings.

  • The Callback URL for an OAuth 1.0a API is: https://mashape.com/oauth/10a/callback
  • The Callback URL for an OAuth 2.0 API is: https://mashape.com/oauth/2/callback

The real callback URL to your application is specified in the Mashape Client constructor instead. For example, this is the proper configuration for an application that's trying to consume Twitter:

Redirect the user

Before consuming the endpoints, your application must be granted permission from the user. You must redirect the user to an auto-generated URL (OAuth Redirect URL) that will start the authorization flow. After successful authentication, the user will be redirected back to a specified URL (the Custom Callback URL) where your application will be able to parse the required OAuth tokens to consume the API endpoints.

You can get the OAuth Redirect URL by invoking the getOAuthUrl("optional scope") method. You will also notice that the constructor of an OAuth protected API requires additional parameters:

You can get the OAuth credentials from the third party service. Most of them, like Twitter or GitHub, allow you to create Applications, and each application has its own pair of keys.

Note: You must execute getOAuthUrl for every new user or every time you need to renew the tokens. Also, the URL expires after a while so redirect the user immediately.

Parse the OAuth Tokens

If the user has granted permissions to your application, we'll redirect him back to the callback URL you specified in the constructor, including two parameters:

  • accessToken
  • accessSecret - only if the API is OAuth 1.0a protected.

For example, if you specified the following Callback URL:

http://myservice.com/path

At the end of the OAuth flow the user will be redirected to:

http://myservice.com/path?accessToken=123456&accessSecret=67890

You can store the OAuth credentials in your database and associate them with the user for every API request.

Authenticating and making requests

Before consuming the endpoint, you must authenticate the clients with the OAuth Tokens, like:

Support & Feedback

This client library is open source. You can contribute on GitHub: https://github.com/Mashape/mashape-php-client-library

Please shoot us an email if you have questions or feedback (support@mashape.com) or open a GitHub issue for bugs and feature requests.