Communicating with Apple Web Services (GSX) via Filemaker 3

 My previous blog talks about communicating with GSX using JSON. There is one area which is not mentioned. This area concerns with security. GSX requires client certificate issued by them and a white-listed IP. They require user to be certified and communicating from an approved IP address.

The white-listing is easy to achieve. Just designate your server/computer as the channel to communicate with GSX. All API requests have to be send from the server/computer. This means that if you require multiple user access, then you must provide a means for all of them to communicate with GSX from the white-listed server/computer from Filemaker using the "Insert from URL" function.

Getting a cert from GSX is done by sending a properly filled CSR to GSX. Note that the Common Name is defined by GSX. It is used to identify user according to GSX format. With the cert, you need to prepare it for use by the server/computer so that you can use it. The following is example done in PHP. The method used is via CURL in PHP.  It is not advisable to use Filemaker to communicate directly with GSX as each "execute from server" means one connection used. You may soon find out you run out of connection on your server. By using "Insert from URL" and calls a PHP server, there is no limit.

Before you could start coding the PHP, you need to prepare your cert for use in CURL. CURL works best with certs in the PEM format. You need to combine the cert and private key into one file by copying and pasting the cert and key into a single pem file.

The following is a typical CURL setting

$ch = curl_init();

curl_setopt($ch, CURLOPT_HEADER, false);

curl_setopt($ch, CURLOPT_VERBOSE, true);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_ANY);

curl_setopt($ch, CURLOPT_VERIFYHOST, 0);

curl_setopt($ch, CURLOPT_VERIFYPEER, 0);

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

curl_setopt($ch, CURLOPT_HEASDER_OUT, true);

curl_setopt($ch, CURLOPT_SSSLCERTTYPE, 'pem');

curl_setopt($ch, CURLOPT_SSLKEYTYPE, 'pem');

curl_setopt($ch, CURLOPT_SSLCERT, 'your cert');

curl_setopt($ch, CURLOPT_SSLKEY, 'your key');

curl_setopt($ch, CURLOPT_SSLKEYPASSWD, 'your pass');

You will have to check the documents to see what are the headers required to be sent to GSX. I suggest you send the header settings from your user to the server/computer as JSON then convert the JSON as array with variable name as $headers as shown above. In addition, not all GSX API calls are POST. You need to get user to indicate whether the request is POST or GET.

If it is post then you will need to set the following

curl_setopt($ch, CURLOPT_POST, true);

curl_setopt($ch, CURLOPT_POSTFIELDS, $content);

curl_setopt($ch, CURLOPT_URL, 'your url');

Since a GET requires CURL GET request, you need to define it with the following.

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

Each API requires the API to be defined as part of the URL. You need to define the URL for each API call. Compose the URL from the user side and send it as a parameter to the server.

curl_setopt($ch, CURLOPT_URL, 'your url');

Finally execute the CURL

$output = curl_exec($ch);

It is a good practice to always close the CURL after every thing is done.

Now CURL may return two different errors. One from CURL itself, the other is from GSX. Your error message have to distinguish between the two.

Before you even start to test the PHP coding, you need to obtain an initial ID from GSX. Therefore, you have to visit https://gsx2.apple.com/gsx/login to sign in and get the ID. This id will be used to obtain the proper ID for subsequent GSX API request by calling the "authenticate token" api then copy the ID returned for subsequent use.

A final oddities is that if you, or your users, use more than one app or one computer that access GSX. Please be reminded that only one ID is provided at anytime. You need to use the same ID for all requests. It is up to you and your user to store such ID in one secure place and use it to consume APIs.