Reward Cloud has now become Tillo - Find out more here

Development | 7 min read | 15/03/2018

APIs at Reward Cloud

Connectivity at the heart of what we do

Personally, my favourite aspect of software development has always been making different systems talk to each other - there’s something inherently exciting about harnessing the power of one system and using it within another to build something greater than the sum of the parts.

Such integrations have a clear benefit to both the providers and consumers of a software service. For the providers, supporting the consumption of your service by others is likely to be fundamental to your business model. By defining a clear set of interactions and the rules required for them to take place, you can allow it to be used as a component in any number of applications outside your own domain. This in turn allows companies consuming those services to focus on their core strengths. So rather than building, for example, their own payment integration or user authentication service they can leverage an existing service that is already out there. Standing on the shoulders of giants as opposed to reinventing the wheel.

These integrations and connectivity are central to the work we do here at Reward Cloud, and this article was written to provide a general introduction to the means by which we achieve this - APIs.

What are APIs?

APIs (application programming interfaces) help achieve communication between software components by clearly defining the methods by which they will do so. A popular analogy for APIs outside of the software world is a wall socket - this acts as an interface to a service (electricity) that is consumed by our everyday appliances. The electricity service conforms to an expected specification (it will deliver a certain number of volts at a particular frequency) which is made available to any appliance that also meets the specification (the appliance has a plug that matches the shape of the socket). In the same way, an API specifies how software components should interact with each other, detailing how one component should make a request for an action to be carried out and how the receiving component should respond.

Without a specification, appliances that wanted to use the electricity service would need to be connected directly to the wires in the walls of the building - this would require a detailed knowledge of how that particular electricity service works. Once connected, we would not be able to move the appliance from one location to another easily. If we did move the appliance, we would not be able to assume that it could be connected to a different electricity service in the same way; similarly, we also could not assume that a second different appliance could be connected to the same service in the same way.

In the software world, a lack of specification between components would result in system integration projects that took longer, were more complex and less reusable.

APIs at Reward Cloud

Our core API services underpin the key operations of our digital gift card network, allowing our customers to find brands and request gift cards in real time. These services in turn make use of a number of internal API services such as our URL hosting service.

As well as building and maintaining our own API, a significant amount of our development time is spent creating and updating software connecting to the specifications of other systems, most notably the payment processors responsible for handling the financial transactions of the brands we sell. No two of these software systems are alike, but our engineers focus on achieving a high quality integration to each of these systems into our platform that is robust and scalable.

The result is seamless availability of gift cards for a wide and ever growing range of household name retailers on the Reward Cloud network. These can be purchased on tap in a simple uniform transaction whether you are ordering Uber, Amazon or Starbucks. Our customers rely on our service to build amazing things, from gift card options on cashback sites and improving employee perks within rewards/incentive schemes to new methods of cashing out cryptocurrencies.

If you need to plug into gift cards as a service on tap - Reward Cloud is your wall socket.

Basics of API design

To give a simple overview of the process of designing part of an API, let’s take as an example a single software component that is responsible for storing and handling updates of orders on a system. Designing an API to allow others to interact with the orders first requires us to come up with a set of useful operations that might be required, such as:

Show a list of all the orders

Show a specific order, eg. order number 123

Create a new order

Update an order

Delete/cancel an order

Now that we have a set of interactions, each of these will be given a route URL. These routes will also be assigned an HTTP verb as appropriate (based on whether the interaction is creating, reading, updating or deleting):

We now need to define request and response messages to be sent to and from each route for the interaction. The format of the specified request and response message is typically either one of two widely used data standards, JSON or XML. JSON is used in the Reward Cloud API as it is easier to read and results in lower file sizes due to having less tags.

Example request/response for show order 123:

Example request/response for create new order:

Good practice and principles

Through our experience of creating, maintaining and connecting to APIs on a daily basis, our engineering team have developed an appreciation of what to aim for and what to avoid when working with APIs in a busy production environment.

At Reward Cloud, we believe a good API should be:

Well documented: provide a clear specification for the routes, headers, requests and responses required to successfully achieve an interaction. Imagine that you are the next developer responsible for connecting to the service, and think what you’d like to see present in order to achieve a successful integration - sometimes code examples are a welcome bonus. At Reward Cloud we currently use Swagger for our API documentation but have seen good recent examples using Apiary and Postman.

Well tested: designed with clear success/failure paths in mind, and proveable through complete unit test coverage.

Secure: if someone asks for something they don’t have permission to access, there must be both authentication to determine their credentials and validation to determine that they have appropriate privileges to perform the requested interaction.

Clear on the causes of any errors: when things go wrong, return something friendly and informative, as opposed to a human-unfriendly software message. Again, imagine that you are the next developer working with the service and have to urgently debug an unexpected error. Use standard HTTP status codes to indicate the status of a response (e.g. 200 OK, 400 bad request, 401 unauthorized), but supplement this with specific error codes and messages to provide greater granularity.

Able to handle/validate against missing, invalid or null request data: never assume that a value will be present in your request data. Catch and throw exceptions as required.

Scaleable: your interaction must be able to be called a large number of times in quick succession (e.g. when handling batch orders) without performance being affected. We achieve this at Reward Cloud through a combination of caching, load balancing and optimising code to keep database lookups to a minimum.

Recommended reads

These two recommended books by Philip Sturgeon illustrate the importance of easy to use, well documented, maintainable APIs - whether maintaining your own services or working with others.