Client

Updated 2,868 Days AgoPublic

Actions

OAuth Client Library

Getting started

This lib lets you easily integrate with DatingVIP REST API using OAuth authentication. In addition to being easy to use it support async calls. You can download it here.

Dependencies

• PHP 5.2 or higher
• DatingVip, OAuthClient and OAuthCurl (included with the repository)

Usage and examples

Our API endpoints requires authentication with every call. Our lib makes it easy by
exposing an extremly simple API.

• get($endpoint[, $params]) - GET request using OAuth
• post($endpoint[, $params]) - POST request using OAuth
• delete($endpoint[, $params]) - DELETE request using OAuth

Accessing the response

All calls toi our APIs return an object with properties. The properties are named
identical to what is in the response and dimensions of 2 or more are exposed as arrays.
For example, the following JSON response is from getting user information API.

{
  username: "jonhdoe",
  title: "John Doe is in the house",
  gender_id: 1,
  gender_id: 2,
}

Each of these values can be accessed the following ways.

<?php
// Access properties directly as member variables
$datingvip->username;
$datingvip->title;
$datingvip->gender_id;
$datingvip->looking_id;

// Access properties as an array through the response property
$datingvip->response['username'];
$datingvip->response['title'];
$datingvip->response['gender_id'];
$datingvip->response['looking_id'];
?>

Exposing the response headers

You can access the response headers for your request by checking the $resp->headers array.

<?php
$resp = $datingvip->get('/account/verify_credentials');
var_dump($resp->headers);
?>

A note on enumerated lists

Some responses are returned as an enumerated list. Since PHP requires that object properties
start with [a-Z_] you cant use ''$resp->0->title''. Given the following JSON response,
you can use either of the methods described below.

[
  {
  username: "johndoe",
  title: "John Doe is in the house"
  ...
 },
 {
  screen_name: "marydoe",
  name: "Marry Doe"
  ...
 },
  ...
]

And PHP

// Access the respose as an array
$first_message = $resp[0]->msg_body;

// Loop over the response as an an array
foreach($resp as $message){
	echo $message->msg_body;
}

Catching and handling exceptions

Our client lib throws an exception anytime the HTTP response code is not between 200 and 399.
For debugging purposes, accessing responseText doesn't follow this pattern and will always return the raw response.
It's recommended that you catch specific exceptions in favor of the base Exception.
Here is an example of catching an DatingVipException and falling back to the base Exception.

<?php
$datingvip = new DatingVip(CONSUMER_KEY, CONSUMER_SECRET, $userToken, $userSecret);
$datingvip->setApi('http://dating-m1.datingvip.com');

try {
	$account_info = $datingvip->get('/account/verify_credentials');
	echo $account_info->title;
} catch(DatingVipNotAuthorizedException $e) {
	echo 'We caught an DatingVipNotAuthorizedException';
	echo $e->getMessage();
} catch(Exception $e) {
	echo 'We caught an unexpected Exception';
	echo $e->getMessage();
}
?>

Exception hierarchy

• DatingVipException extends Exception - General uncaught or unknown exceptions
• DatingVipBadRequestException extends DatingVipException - 400 response code
• DatingVipNotAuthorizedException extends DatingVipException - 401 response code
• DatingVipForbiddenException extends DatingVipException - 403 response code
• DatingVipNotFoundException extends DatingVipException - 404 response code
• DatingVipNotAcceptableException extends DatingVipException - 406 response code
• DatingVipEnhanceYourCalmException extends DatingVipException - 420 response code
• DatingVipInternalServerException extends DatingVipException - 500 response code
• DatingVipBadGatewayException extends DatingVipException - 502 response code
• DatingVipServiceUnavailableException extends DatingVipException - 503 response code

Uploading images using multipart

We supports uploading images via the DatingVip API using OAuth. To specify the image parameter to the account/update_profile*image endpoints
you'll need to prepend the key and value with an @. The path to the file must be the absolute path to the file on the server.

// TODO: Create working example of image uploading

Using the oauth_callback parameter

In the 1.0a version of the API we added support for an oauth_callback parameter. This parameter allows you to programmatically specify the callback url which DatingVip redirects to.
Originally, DatingVip would always redirect the user back to the URL you specified in your OAuth settings.

To specify a different callback url you can pass in a parameter into getAuthorizeUrl.

<?php
$url = $datingvip->getAuthorizeUrl(null,array('oauth_callback' => 'http://mysite.com/custom/callback'));
echo '<a href="<?php echo $url?>">Authorize with DatingVip</a>';
?>

DatingVip associates the URL you specified with the OAuth token they give back to you. This url works like normal and when the user visits it
they will be taken to DatingVip OAuth page as normal. Once they authorize usage of your application then DatingVip will forward the user to the URL you specified.
They will include an additional parameter in the url named oauth_verifier. This parameter needs to be passed in to getAccessToken in order to exchange the request token for an access token.
Aside from these two additional parameters the flow is identical except you can specify the callback URL at run time.

<?php
$datingvip->setToken($_GET['oauth_token']);
$token = $datingvip->getAccessToken(array('oauth_verifier' => $_GET['oauth_verifier']));
$datingvip->setToken($token->oauth_token, $token->oauth_token_secret);
$account_info = $datingvip->get('/account/verify_credentials');
echo $account_info->username;
?>

Efficiently using asynchronous curl

Knowing that curl calls are expensive, we don't want to wait around idly while we could be doing other work.
This is especially true if you need to make multiple calls on a single page. Ideally, you could fire off several requests
in parallel instead of doing them one at a time. To enable asynchronous calls you will need to call
useAsynchronous(true) on the DatingVIp object.

The key to using DatingVip lib efficiently is to delay accessing the results for as long as possible.
Initiating the call fires off the HTTP request and immediately returns control back to you without blocking.
The call continues to work in the background until you need the results. For the best performance it's
advised to initiate the calls as early as possible and only block by accessing the results as late as possible.
The implementation details depend greatly on your framework.

<?php
$datingvip = new DatingVip(CONSUMER_KEY, CONSUMER_SECRET, $userToken, $userSecret);
$datingvip->setApi('http://data-m1.datingvip.com');
$datingvip->useAsynchronous(true);

// TODO: create working example of async calls
?>