APIs

In this tutorial, we're going to take a look at the Marvel API, a tool provided by Marvel for developers to get access to the 70-plus years of Marvel comics data.

First, we'll walk through the steps in which one can acquire the keys needed to make requests to the API. Then, we'll look at the tools we can use to test out the API. Finally, we're going to build a website that uses the API.

Signing Up

The first thing we need to do is go to the Marvel Developer Website and click the Get a Key link. We'll then be provided with the public and private key which we can use to perform requests to the API. If you plan to use the project in production, you can also add your website's domain name to the list of authorized referrers. This provides a security layer in case you accidentally push your public and private keys to Github.

Important Notes Regarding the Use of the API

For limits and rules, please see the attribution, linking and rate limits page of their documentation. Also be sure to read the Marvel API Terms of Use if you're planning to use the API in production. I've summarized it below:

• Beware of the API rate limit. At the time of writing of this tutorial the rate limit is 3000 calls per day. That's applicable to all the endpoints.
• Always attribute Marvel as the source when displaying API data and images. Marvel recommends the use of this text: Data provided by Marvel. © 2016 Marvel.

Playing with the API

The API comes with an interactive documentation which allows you to easily test all the available API endpoints.

There's information on the data one can expect:

... text fields to specify the different parameters to be submitted for the request:

... error status codes:

... the request URL, response body, response code and the response headers:

Do note that the request URL won't actually return anything if you access it outside of the API testing tool. This is because it lacks the required parameters for the request. At the bare minimum, you'll have to supply the public key, the current unix timestamp, and an md5 hash of the timestamp, and private and public key combined.

<?php
$ts = time();
$public_key = 'your public key';
$private_key = 'your private key';
$hash = md5($ts . $private_key . $public_key);

Once you have those, only then can you perform a request to the API:

<?php
$query_params = [
    'apikey' => $public_key,
    'ts' => $ts,
    'hash' => $hash
];

//convert array into query parameters
$query = http_build_query($query_params);

//make the request
$response = file_get_contents('http://gateway.marvel.com/v1/public/comics?' . $query);

//convert the json string to an array
$response_data = json_decode($response, true);

We'll take a look at this in more detail when we get to the section where we start making requests for the app that we'll be building.