PHP Client

Overview

Download the file and change the name from fireapiclient_php.txt to FireApiClient.php

• FireApiClient.php  version 0.9.4

The API Client will build and make HTTP requests for you and return the response as an object. On error, it’ll throw an exception.

For the server object creation, add these addresses to the call:

'base_url’ => 'https://api.fimnet.fi',
'auth_base_url' => 'https://auth.fimnet.fi'

Example:

$client = new FireAPIClient(array(
  'client_id' => 'my_client_id',
  'client_secret' => 'my_client_secret',
  'access_token' => 'my_access_token'
));

$user_list = $client->get('/users'); 

Constructor options

The constructor takes an array of options. You can pass the following options:

• client_id: Your API client ID (required).
• client_secret: Your API client secret (required).
• access_token: Your Access Token (required, expect during authentication).
• base_url: The Fire API base URL. Default is https://api.fimnet.fi
• auth_base_url: The Fimnet Login base URL. Default is https://auth.fimnet.fi
• public_key: The Fimnet Login SSL public key, used to verify ID Token signature. Default is coded in the class.
• throw_exceptions: Whether to throw exceptions on API error or not (default is true)
• decode_json: Whether to automatically decode the API response and return an object or not (default is true).

Fire API methods

To query the API, you can use one of the following 4 methods:

• get($url)
• post($url, array $data)
• upload($url, array $data)
• put($url, array $data)
• delete($url)

Example:

$client = new FireAPIClient(array(
  'client_id' => 'my_client_id',
  'client_secret' => 'my_client_secret',
  'access_token' => 'my_access_token'
));

// get a user object  
$user = $client->get("/users/$id");

// update a user object 
$client->put("/users/$id", array("phone' => "+3581234"));

File upload

To upload a file with the client, you need to use the upload methon and pass the full path to the file starting with "@". Example:

$client->upload("/users/$id/avatar", array('file' => '@/path/to/my/file.png'));

Fimnet Login methods

During authentication, you can use the following methods:

getAuthorizeUrl(array $parameters)

The method accepts the following parameters:

• state: your anti-forgery state token
• redirect_uri: the callback URL

The method returns a URL (string).

Example:

$client = new FireAPIClient(array(
  'client_id' => 'my_client_id',
  'client_secret' => 'my_client_secret',
));

$url = $client->getAuthorizeUrl(array(
  'state' => $random_state,
  'redirect_uri' => $redirect_uri
));    

getAccessToken(array $opt)

The method accepts the following parameters:

• code: the authorization code
• redirect_uri : the callback URL
• decrypt_id_token: Whether to automatically decrypt and verify the ID Token (default is true)

The method returns an object like the following:

stdClass Object
(
    [access_token] => f468cd1e68bb664a436f1b17221bef6a0ea57905
    [expires_in] => 3501
    [token_type] => Bearer
    [scope] => openid
    [id_token] => stdClass Object
        (
            [iss] => auth.fimnet.fi
            [sub] => 1234
            [aud] => test
            [iat] => 1400160003
            [exp] => 1400163504
            [auth_time] => 1400159904
        )
)

Example:

$client = new FireAPIClient(array(
  'client_id' => 'my_client_id',
  'client_secret' => 'my_client_secret',
));

$client->getAccessToken(array(
  'code' => $_GET['code'],
  'redirect_uri' => $redirect_uri
));      

getUserinfo()

This method can be called after getting the access_token with getAccessToken(). It returns basic information about the logged in user:

Example:

$client = new FireAPIClient(array(
   'client_id' => 'my_client_id',
   'client_secret' => 'my_client_secret', ));

$client->getUserinfo();

Exceptions

On error, the client will throw different types of exceptions.

FireApiClient_Exception (subclass of Exception)

An error occured in the client itself (typically cURL error).

FireApiClient_ApiError (subclass of FireApiClient_Exception)

An error occured with your API call, for example endpoint not found, bad request, etc.

You can use getMessage() to get the error message and getCode() to get the HTTP status code (404, 500, etc.).

FireApiClient_OAuthError (subclass of FireApiClient_ApiError)

An error occured related to OAuth 2 protocol (bad credentials, malformed header) or during Fimnet Login.

In addition to getCode() described above, you can use getMessage() to get the OAuth 2 error code, and getDescription() to get the OAuth 2 error description.

FireApiClient_ValidationError (subclass of FireApiClient_ApiError)

This is a specific class for HTTP 422 errors (unprocessable entity), also know as "validation errors". They happen when a required field is missing, or doesn't have the right format, etc.

In addition to getMessage() and getCode() described above, this class of exceptions also add getErrors() which returns the array of errors.

Other methods

• getLastBody() returns the last raw data returned by the API
• getLastStatus() returns the last HTTP status code
• getLastHeaders() returns the last headers returned by the API
• getLastRequest() returns the last request made to the API