cloudwelder/petitions-api

This package provides a wrapper for Petitions.io REST Api

0.4 2017-06-02 06:17 UTC

Requires

• php: >=5.5
• guzzlehttp/guzzle: ~6.0

Requires (Dev)

• phpunit/phpunit: ^6.1

MIT

• Reneesh Tk
• Alwin Tom

• php
• api
• petitions

README

This is PHP wrapper to Petitions.io API

Contents

• Installation
• Pre-requisites
• Usage
  • Initializing the API
    • Method 1: Using Credentials
    • Method 2: Using Personal Access Token
  • Generating Login URL
  • Acquring Access Token
  • Making API Calls

Installation

Installation is done using composer. Run the following command to include this package into your project
composer require cloudwelder/petitions-api

Pre-requisites

In order to use this package, you must have an active App at petitions.io. If you dont already have one, register for one at petitions.io After the registration, note down your client_id, client_secret and redirect_uri OR you could get a personal access token directly.

Usage

Make sure you have the following line in your code before using any of the API classes. Thi is not required if you are using a framework such as laravel.

require "vendor/autoload.php"

Initializing the API.

To use any of the APi calls, you must first get an instance of the API and acquier an access token using any of the following methods.

Methods 1: Using API credentials.

use CloudWelder/PetitionsApi/PetitionsApi;

$api = new PetitionsApi('client_id', 'client_secret', 'reidrect_uri');

Substitute client_id, client_secret, redirect_uri with your own values.

Generating Login URL

To gain access rights from a user, you must first redirect him to petitions.io. You can use the getRedirectUrl() method to generate this url.

$redirectUrl = $api->generateRedirectUrl();

You can then use this url to reidrect the user or as the href of an html link.

echo "<a href='$redirectUrl'>Click here to login</a>";

Acquiring Access Token

Once the user has granted your app's access request, petitions.io will redirect the user to the url you have specified in redirect_uri settings in petitions.io. This is where you should acquire the access token using the autthorization code trnsmitted as part of the url.

$token = $api->generateTokenFromCode($_GET['code']);
$accessToken = $token->getAccessToken();

Store this access_token into data base or other persistant storage to use it later. Unless the user revokes the grant, this access token is valid for a long time (a year)

The Token object retuned will also contain a refresh_token in addition to access_token. You can retrive it using getRfreshToken() function. Rrefresh tokens can be used to regenerate the access token when they expire.

Method 2: Using Personal Access Token.

If you alreay have an active personal access token, you can initialize the API without any credentials

use CloudWelder/PetitionsApi/PetitionsApi;

$api = new PetitionsApi();

Making API calls

The API object provides four methods for making API calls. They all return an instance of CloudWelder/PetitionsApi/Response. The returned object contains HTTP response related information such as headers, statsu code and response content. Petitions.io always return response in JSON format. So you must parse the response body to actually use the data. However the ressponse opbjecthas a helper method getResponseData() whcich will return an associative array generated by parsing the response content.

Before making any API calls, remeber to set the access token using the withToken() method. This method is chainable so you can chain other methods to it.

The four API call methods are:

• get() Used for making GET request to API end points. Signature: get($url, $data)
  • $url The API end point
  • $data An associative array containing any data to be passed along with the call. Example:

//Get the details of the active user.
$response = $api->withToken($accessToken)->get('users/me');
$userDetails = $response->getResponseData();

• post() Used for making POST requests to API end points.
  Signature: post($url, $data)
  • $url The API end point
  • $data An associative array containing any data to be passed along with the call. Example:

//Create a new petition.
$petitionData = [
  'title' =>  'My petition',
  'description' => 'This is a sample petition'
];
$response = $api->withToken($accessToken)->post('petitions', $petitionData);
$createdPetition = $response->getResponseData();

• put() Used for making PUT requests to API end points.
  Signature: put($url, $data)
  • $url The API end point
  • $data An associative array containing any data to be passed along with the call. Example:

//Edit an existing petition
$petitionData = [
  'title' =>  'My new petition'
];
$response = $api->withToken($accessToken)->put('petitions/2', $petitionData);
$changedPetition = $response->getResponseData();

• delete() Used for making DELETE requests to API end points.
  Signature: put($url)
  • $url The API end point Example:

//Delete a petition
$response = $api->withToken($accessToken)->delete('petitions/2', $petitionData);