Technical explanation

API Explanation

Gigatribe API is a collection of http services protected by Gigatribe OAuth 2.0. To call these functions, developers have to provide proper authentication headers, for example, a valid access token, or your application's id and secret. If you're new to OAuth, please first read our introduction, or go to OAuth website or read the RFC specification.

Gigatribe PHP Client Library

In order to help developers write less code to call an API, we've developped this client library which encapsulated the code for asking for authorization code, access token and the code for calling an API.

Gigatribe PHP client library helps to call Gigatribe API in a more simple and standard way. Instead of initializing CURL every time by sending options to it, now you can just call a few functions to complete the access token requiring process. Gigatribe API object will keep the basic user information and token data for you. After you obtain an access token, there will be no more need to pass it to the http request every time. Our library automatically does that for you. It is just this simple.

Preparation work

To use our library, we assume that you already know the basics of PHP and CURL manipulations. Also we assume that your PHP server supports CURL and JSON.

include "/lib/gigatribe_api.php";
$config = array(
	"client_id" => '28df2dcfda000ee34a99afb6ab600ae284eb3a9c9b0c19ef61c021d9823b0f45',
	"client_secret"=> '2514e7451fcd9d5610674e9d67b8d9d39ba86bbe32344af7e08dae84b994058e'
);
$gt = new gigatribe_api($config);

Authorization Code

Before everything happens, your application redirects the user to authorization page, for example: https://www.gigatribe.com/en/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://www.YOUR_SITE.com/oauth_callback.php. If the user authorize your application, the user browser will be redirected to http://www.YOUR_SITE.com/oauth_callback.php?code=AUTH_CODE_FOR_YOU. So be sure to accept an authorization code on your oauth_callback.php and store it for later usage.

Obtaining an Access Token

To request an access token, you must provide an authorization code, a redirect URI and a response type. An authorization code is what you will receive after the user authorize your application and with what you can exchange for an access token. The redirect URI is the identical URI which was set during the authorization process.

By presenting this code, you are permitted to request for an access token. Note that here the second parameter redirect URI is optional. If you don't set it, it'll be the URL of current page.

$code = $_GET["code"];
$gt->request_access_token_from_code($code, "http://www.yoursite.com/callback.php");

Retrieving User Information

Before you call any API, it may be a good idea to obtain his/her basic information, such as email, username, id, etc. This will come handy in later requests. You can do this be calling get_user_info().

$current_user = $gt->get_user_info();

Calling APIs

Now you are ready to call an API, with the information you've got. You have the access token, user ID, username and his email.

Gigatribe APIs are either public or private. Public APIs don't need an access token, while private APIs are protected by OAuth protocol, meaning you must present your valid access token to use private APIs. You must specify whether authentication is needed when calling the API by setting the fourth parameter in your function call.

$contact_list = $gt->api("/contacts/show", "GET", null);

Remember that this result is in JSON format, so it may be necessary to call json_decode() to get an object or an array.

Example

include "/lib/gigatribe_api.php";
session_start();

// use your client id and secret
$config = array(
	"client_id" => '4308cb60e4c306043958d49c53758924a2cdcead76c3b9d02f15ca5f1f727846',
	"client_secret" => 'a12971819f23b35d3913376cba7db1c687b677c8d5456aaf931e6ef18b080254'
);

$gt = new gigatribe_api($config);

$code = $_GET["code"];
if (isset($code)) {
	// if code is set, request an access token
	$gt->request_access_token_from_code($code);
	
	// choose the way to store your token
	$_SESSION["token"] = $gt->get_access_token();
	$_SESSION["expire"] = $gt->get_token_expire_time();
	
} elseif (isset($_SESSION["token"])) {
	// retreive the token
	$gt->set_access_token($_SESSION["token"]);
	$gt->set_token_expire_time(intval($_SESSION["expire"]));
}


// try calling these APIs 
$tribes = $gt->api("/tribe/search", "GET", array('words'=>'video game', 'page'=> 2, 'count' => 25));

$my_info = $gt->api("/user/me/show", "GET", null);

$my_contacts = $gt->api("/contacts/show", "GET", null);

$category = $gt->api("/category/250/show", "GET", null);

Errors

During your development, you may encounter several errors from our server. Here is the list of most possible errors, their definitions, their meanings.

An error is an array. All errors have a field "error", most errors have a field "message" for a brief explanation.

Error Code Explanation
invalid_request Caused by invalid parameters (not recognized, invalid format, wrong value, missing parameter, etc).
invalid_grant When requesting an access token by giving an authorization code, this error could be caused by a code invalid, not existing, or belonging to another application.
unauthorized_client The client id could not be found.
access_denied The user denied the request.
token_not_found The access token could not be found.
unsupported_response_type At the moment, the only supported response type is "code".
unsupported_grant_type At the moment, the only supported grant type is "authorization_code".
code_expired The authorization code has expired.
token_expired The access token has expired.
server_error An server error happened.