joshleaves/techshaker-api-php

TechShaker API

TechShaker API PHP

PHP wrapper to access the TechShaker API., _(*1)

Installation

Using Composer:, _(*2)

php composer.phar install techshaker-api-php

Getting started

Once techshaker-api-php is installed, grab your pair of API keys from TechShaker and use theses to create your client instance., _(*3)

<?php
    require 'vendor/autoload.php';

    $API_KEY = 'foo';
    $API_SIG = 'bar';
    $TS = new \TechShaker\Client($API_KEY, $API_SIG);

Issuing HTTP REST calls

You can issue HTTP REST calls to the API without library wrapping using the methods \TechShaker\Client->get($path), \TechShaker\Client->post($path, $args), \TechShaker\Client->put($path, $args) and \TechShaker\Client->delete($path) with each method's name describe the HTTP method used., _(*4)

For all four methods, $path will refer to the target path (minus the API's base URL) and $args will be an Array of key=>values properties to pass to the server., _(*5)

Resources wrappers

\TechShaker\User

User resources are obtained with \TechShaker\Client->getUser($screen_name) with $screen_name being the target user's Twitter username. This method returns a NULL on error., _(*6)

Methods

\TechShaker\User->isEditable()

Returns true if you can edit the current user. You can only edit your own user profile., _(*7)

\TechShaker\User->getInfos()

Returns all available infos about the current user., _(*8)

\TechShaker\User->updateInfos($args)

Performs a PUT value on the target user using the key=>values provided in the array $args. Returns a boolean indicating success., _(*9)

Example usage

<?php
$RED = $TS->getUser("joshleaves");
if (!$RED) die("This can't happen...");
$INFOS = $RED->getInfos();
$ERR = $TS->getUser("error_i_dont_exist");
if (!$ERR) die("Error: " . $TS->getLastError());
if (!RED->isEditable()) {
    echo "You can edit yourself!" . PHP_EOL;
    if (!$RED->updateInfos(Array("github" => $INFOS["github"])) {
        die("Error: " . $TS->getLastError());
    }
} else {
    die("This is not you...");
}
echo "User found, read and modified!" . PHP_EOL;
?>

Entity resources

GET methods

\TechShaker\Entity->getInfos()

POST methods

\TechShaker\Entity->addMember($args)

\TechShaker\Entity->addAttended($args)

\TechShaker\Entity->addAttending($args)

\TechShaker\Entity->addBacked($args)

\TechShaker\Entity->addBacking($args)

PUT methods

\TechShaker\Entity->updateMember($screen_name, $role)

\TechShaker\Entity->updateAttended($relation_id, $args)

\TechShaker\Entity->updateAttending($relation_id, $args)

\TechShaker\Entity->updateBacked($relation_id, $args)

\TechShaker\Entity->updateBacking($relation_id, $args)

DELETE methods

All DELETE wrappers only take one argument which is either relation_id for all entity-to-entity relationships, or screen_name for memberships., _(*10)

// Remove a member
\TechShaker\Entity->removeMember($screen_name) ####

// Remove attendance (from a startup's POV)
\TechShaker\Entity->removeAttended($relation_id) ####

// Remove attendance (from an incubator/accelerator's POV)
\TechShaker\Entity->removeAttending($relation_id) ####

// Remove a backing (from a startup's POV)
\TechShaker\Entity->removeBacked($relation_id)

// Remove a backing (from a VC's POV)
\TechShaker\Entity->removeBacking($relation_id)

Upon success, all methods return:, _(*11)

HTTP/1.1 200 OK
{ "status": "SUCCESS" }

Possible errors:, _(*12)

• 401: Your API tokens are not valid., _(*13)

• 403: You don't have the right to issue DELETE methods on this entity., _(*14)

• 404: The target member/relation doesn't exist., _(*15)

• 500: Something worse happened., _(*16)

Error handling

TechShakerError objects

All error generate a TechShakerError object. TechShakerError objects contain the HTTP statusCode of the error and a description of the error. Properties can be read like a normal array or returned using getters., _(*17)

<?php
    $error = new TechShakerError(42, "Life, universe and everything");
    echo "_" . $error . "_" . PHP_EOL;
    // _42: Life, universe and everything_
    echo $error->getStatusCode() . " => " . $error->getErrorString() . PHP_EOL;
    // 42 => Life, universe and everything
    echo $error["code"] . "_" . $error["statusCode"] . "_" . $error["error”] . PHP_EOL;
    // 42_42_Life, universe and everything
    echo ($error["error"] == $error["errorString"] ? "TRUE" : "FALSE") . PHP_EOL;;
    // TRUE
?>

On GET methods

Except for \TechShaker\Client->getUser($screen_name) and \TechShaker\Client->getEntity($url_name) which return a NULL on error, all GET requests that fail will return a TechShakerError. Thus, you should always check your return values for the presence of an "error" member., _(*18)

<?php
    $another_user = $TS->getUser("i_dont_exist"):
    if (!$another_user) {
        die("Error:" . $another_user);
    }
    $another_user = $another_user->getInfos();
    if (isset($another_user["error"])) {
        die("Error: " . $another_user);
    }
    echo "This user's real name is: " . $another_user["person_name"];
?>

On PUT/POST/DELETE methods

Methods that call for a modification of data return a boolean indicating whether the request succeeded or not. When the method didn't succeed, a new TechShakerError is generated and can be accessed using the getLastError() method of the client instance., _(*19)

<?php
    $another_user = $TS->getUser("clearly_not_me");
    if (!$another_user) {
        die("Error: No such user.");
    }
    if (!$another_user->updateInfos(Array("foo" => "bar")) {
        $error = $TS->getLastError();
        switch ($error["code"])
        {
            case 403: die("403: Forbidden, you can't edit this user");
            case 422: die("422: Unprocessable, wrong input");
            default: die("500: Something wrong happened.");
        }
    }
    echo "Everything went fine!" . PHP_EOL;
?>