Communicating with the Jomres API

Ok, so you've decided that you want to build an App on another website which will then call your Jomres installation to pull information out for display elsewhere. You've created an API client id and secret, so how do you use that to talk to Jomres?

First a little background.

Jomres uses the OAuth2 standard to provide limited access to functionality through a REST API which uses the HTTP protocol to communicate.

Lot's of acronyms, much technical.

I've always found that the best way to learn is to find practical applications for a subject, so let's just dive right in and do that. Make sure that the client you've created has the right to Get the user's email address. If you're already familiar with using REST APIs, then you can probably just skip to the bottom to the example script.

Now, your Jomres installation is at https://www.example.com. Assuming that you're running Jomres 9.8 or later, then the path to the API is through https://www.example.com/jomres/api

On another server ( localhost is fine) create a script index.php, and in that put

$client_id = 'XXXXXXXX'; // Edit to use your own Client ID & Secret
$client_secret = 'XXXXXXXXXXXXXXXXXXXX';

$server = 'https://wwww.example.com/jomres/api/'; // Your test server's location

 Next we'll create an array which will be posted to server.

$data=array('grant_type' => 'client_credentials' , "client_id" => $client_id , "client_secret" => $client_secret);

Then we'll send our request to the Jomres server to get our access token, which we'll need if we want to pull any information off the server.

$token_request = query_remote_server( $server , "" , "POST" , "/" , $data  );
$response = json_decode($token_request['result']);

The token will be in the $response variable, so let's check it, and if it's set we can go ahead and use it to pull information from the server.

if (isset($response->access_token))
        {
        $token = $response->access_token;

Now we can send our request for the email address

$result = query_remote_server( $server , $token , "GET" , "email" , array()  );

 And voila, if we dump the contents of $result then we'll have the email address.

If the client credentials were wrong, then you'll have something like

{"error":"invalid_client","error_description":"The client credentials are invalid"}

in the response.

 The full script, with more error checking

$client_id = 'XXXXXXXX'; // Edit to use your own Client ID & Secret
$client_secret = 'XXXXXXXXXXXXXXXXXXXX';

$server = 'https://wwww.example.com/jomres/api/'; // Your test server's location

$data=array('grant_type' => 'client_credentials' , "client_id" => $client_id , "client_secret" => $client_secret);

try
    {
    // First let's get our access token
    $token_request = query_remote_server( $server , "" , "POST" , "/" , $data  );
    $response = json_decode($token_request['result']);

    if (isset($response->access_token))
        {
        $token = $response->access_token;
        // Now that we've got the access token, we can request access to the API
        
         $result = query_remote_server( $server , $token , "GET" , "email" , array()  );

        if ($result['result'] != "")
            {
            var_dump($result['result']);exit;
            }
        else
            {
            var_dump($result['status']);exit;
            }
        }
    else
        {
        throw new Exception("Error, json & token not returned ".$token_request);
        }
    }
    catch(Exception $e)
    {
    echo 'Message: ' .$e->getMessage();
    }
    
    
function query_remote_server( $server , $token="" , $method="GET" , $request ="" , $data=array() )
    {
    $ch = curl_init($server.$request);

    switch ( $method )
        {
        case 'POST':
                curl_setopt($ch, CURLOPT_POST, true);
                curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
            break;
        case 'DELETE':
                curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
            break;
        case 'PUT':
                curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
                curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
            break;
        default :
            break;
        }
    
    if ($token != "")
        {
        curl_setopt($ch, CURLOPT_HTTPHEADER, array(
            'Authorization: Bearer '.$token,
            'Accept: application/json',
            ));
        }
    
    curl_setopt($ch, CURLINFO_HEADER_OUT, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30); //timeout after 30 seconds
    curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
    $result=curl_exec ($ch);
    $status = curl_getinfo($ch);
    return array ("result" => $result , "status" => $status );
    }