Download the PHP package mpemburn/api-consumer without Composer

API Consumer

About

The api-consumer package allows you to create simple endpoint wrappers for RESTful API's.

Installation

You can install this package via composer:

composer require mpemburn/api-consumer

The package will automatically register the service provider ApiConsumerProvider.

Next, you will need to publish the package in order to copy api-consumer.php into your config directory:

How to use

Configuration

The package will add the file config/api-consumer.php to your project. This returns an array containing the keys and variables used by the endpoint classes you'll create to consume one or more RESTful APIs. The format will look like this:

'shopify' => [
    'base_uri' => 'https://mystore.myshopify.com/admin/api/2020-10',
    'username' => '5ac3bd00f1ebc6a65caa4c0a6a3b1555',
    'password' => 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
],

To make this more secure, you should store the actual variables in your .env file:

SHOPIFY_USERNAME=5ac3bd00f1ebc6a65caa4c0a6a3b1555
SHOPIFY_PASSWORD=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

...and reference them like this:

'shopify' => [
    'base_uri' => 'https://mystore.myshopify.com/admin/api/2020-10',
    'username' => env('SHOPIFY_USERNAME'),
    'password' => env('SHOPIFY_PASSWORD')
],

You can add as many API's as you need to the config file, as long as each has the API name (i.e., 'shopify' in this instance) at top-level of the array.

NOTE: After making changes to a this config file, it's important to run:

Class Structure

While there's no absolute requirement to structure your class files this way, the suggested heirarchy is:

Parent Endpoint Classes

Each parent endpoint class (e.g., ShopifyEndpoint, DiscourseEndpoint above) needs to extend this package's AbstractEndpoint class. Individual endpoints then extends its primary class. For example:

It's important to return the exact same name from getApiName() that you specified in the api-consumer config file.

NOTE: No headers are assumed, so you should add them in the constructor as shown above.

Endpoint Classes

An individual endpoint should be structured like this:

Making Requests

A simple example of making a request with a GET endpoint:

POST Requests

To create a POST endpoint:

The request might look like this:

The $request in this case should contain and array whose key match those specified in the API documents.

URL's with variables

Some API endpoints require variable parts in the URL string. For example, if you need to update a user, the API endpoint might include the user's ID as part of the URL:

In this case, you would set up your PUT endpoint something like this:

Here, the update method takes the $userId and array of the data to be updated ($userData). The setParams method will add all of the $userData to a Larvel Collection, and the addUrlParam method adds $memberId to a similar collection.

Next, in the getEndpoint method, we can pass the URL string with user_id enclosed in curly braces, which causes it to be seen as a variable. Passing this into the hydrateUrlParams method along with a call to getUrlParams will replace {user_id} with whatever was passed into the update method.

NOTE: You can pass as many variables as needed using this method.

API's That Use Authorization (auth) Tokens

Some API's require you to use an auth token for each endpoint call. The typical pattern is to fetch the auth token by sending a GET request to the API with a secret key provided to by the API's developer's console. Once you have the auth token, you add it to the request parameters for each subsequent call.

This package supports this model by allowing you to create a special endpoint for the purpose. For example:

To call this, your GetAuthToken endpoint should look like this:

Here the $authTokenFetchKeyName property refers to the parameter name of the API key, and the $authTokenResponseName refers to the name that the API assigns to the auth token. The response might look like this:

In addition, your parent endpoint needs to include a reference to the GetAuthToken class:

By default, the token will be discarded after each request. This is usually a good idea since many/most auth tokens are time limited. In the case where you need to make a series of requests in rapid succession, you can use the preserveAuthToken method of the RequestManager:

NOTE: The preserveAuthToken call must come before call to send.