Utilizing a REST-Based Approach to Web Services Technology
The PaymentKeys Application Framework API has been designed to take advantage of many of the best principles and recent advancements in web service technologies - including a REST-based approach to web services.
At its core, REST is simply a return to the basic principles of hyperlinking and using some of the basic methods of the HTTP protocol like POST and GET that made the world wide web so popular for retrieving data and exchanging information with web resources.
Please note that we use the term 'REST-based' instead of claiming a pure REST approach to our API methodology.
Although there is much debate about what makes for proper REST implementation, the PaymentKeys Application Framework focuses on the core principles of REST that make it so attractive as an alternative to the SOAP protocol for web services.
Specifically, a REST-based approach provides more widely established, compatible standards for exchanging data, a lighter data footprint, and broader flexibility and control over underlying data elements and rules.
The PaymentKeys REST Application Server Endpoint
The following URL is the secure endpoint to which all REST-based API calls to the PaymentKeys Application Framework servers will be made:
https://www.paymentkeys.com/api.rest/appserver
The Template for a Standard REST API Request¶
REST-based API calls are sent to the PaymentKeys REST Server as standard HTTP POST or GET requests.
Either method you choose for sending the API request will be accepted.
Data Fields Required In Each REST API Request
Your application needs to provide the following fields in every REST API request:
>| Field Name | Usage | Data To Be Sent |
| api_keyID | Required |
The unique PaymentKey registered by your organization during sign-up. |
| api_sig | Required | This field will contain a base64 encoded HMACSHA1 hash signature of the JSON string value in the api_call field.
Please see the Authentication
document of this wiki for more details and code examples. |
| api_call | Required | A JSON string containing the API command to execute and its associated command parameters |
Using a REST approach, your application will send these fields and their URL-encoded values as traditional name/value pairs in an HTTP POST or GET request.
As you may have noticed, the actual API command and its parameters will be contained in the "api_call" field as a JSON string.
The other fields listed provide the PaymentKeys Application Framework server with the data necessary to identify the sender of the API call, authenticate the sender and the integrity of API call and to specify the format in which the response should be sent.
The reasons and advantages for separating the API command elements into a JSON string will become very clear as we move forward.
The Basic Structure of a JSON API Call
The following is a sample JSON string value for the api_call field that demonstrates the basic structure of an API command to the PaymentKeys Application Framework:
{"command":"paymentkey.activate","version": "1.0","api_call_id": "1AC4F-99B543-7FC0E","some_parameter1": "some_value1"}
The data elements of this string are adhere to the following structure:
>| Field Name | Usage | Data To Be Sent |
| command | Required | The specific framework API command to execute |
| version | Required | The version of the command to execute as defined in the API documenation. |
| api_call_id | Required | A unique id assigned to the API call that allows the PaymentKeys servers to ensure that this specific command is only sent once and can never be sent again.
More about how this works and why its necessary can be found under the Authentication document of this WIKI. |
| Conditional | Optional or required fields to be included as a parameter for the API command (method) being executed. |
If you are not familiar with how to read and understand JSON structures, please refer to
http://www.json.org for more information.
The Reasons and Benefits of Using JSON For API Calls
Although we could have simply allowed each of these fields in an API call to be defined as tradtional HTTP POST or GET fields in the primary REST API request, there are several reasons why JSON was chosen as the data format for delivering the specific API command and parameters to be executed:
1. Object Serialization and Deserialization
A JSON string is simply a string that represents the structure and values of a complex runtime object.
Most popular programming languages provide tools or libraries to serialize a complex object directly into a JSON string and to deserialize a JSON string back into a complex object.
In contrast, constructing an HTTP POST or GET request usually requires the programmer to concatenate strings of name/value pairs together for each separate HTTP request.
The ability to easily serialize and deserialize a variety of different objects using JSON means that the PaymentKeys Application Framework can greatly simplify the programmer's development and interaction with the framework by providing pre-constructed classes through a traditional web service WSDL file for stubbing classes (objects).
These objects can then be used to simplify the contruction of api calls and the handling of the API responses.
2. JSON Strings Are Much Easier For Message Hashing
Most REST-based API's available on the web today require developers to take the name/value pairs of the typical REST API request and concatenate them in alphabetical order by field name in order to generate a hash signature that is based on consistent data for both parties.
Using a JSON string removes this unnecessary level of complexity and work for API developers.
You simply serialize your WSDL stubbed object containing your API command data into a JSON string (or concatenate the JSON string yourself - your choice), hash the JSON string as it is, assign the JSON string to your
api_call variable of your HTTP POST or GET request and the PaymentKeys Application Framework has the exact string you serialized for authenticating your hash signature.
Putting It All Together - A Sample REST-Based API Request
Based on the rules and structures defined in this REST-based template, a command sent through the PaymentKeys Application Framework API using an standard HTTP GET request would look something like this (minus the whitespace, line breaks and lack of URL encoding for readability):
https://www.paymentkeys.com/api.rest/appserver?api_keyID=SomeCompany.pk
&api_sig=BuVwMhtnGPUh3u7wU/NGBnZ0hus=&api_call={"command":"paymentkey.activate","version":"1.0","api_call_id":"1AC4F-99B543-7FC0E","some_parameter1":"some_value1"}&api_output=json