Explaining our principles – how we design our APIs
When launching Access Worldpay, our leadership team first established the principles and practices that would guide how we all work together, as well as the standards to use when designing and developing our services. This article explains how these principles inform how we build our suite of market-leading APIs.
Four clear principles lie at the heart of our API design:
- Simplicity: we design our APIs to make working with them as easy as possible. For example, they’re deliberately developed as self-service software that are straightforward to learn.
- Clarity: our APIs make it clear at each stage the next steps to take; they also come with all the documentation and certification you need to integrate them with your own systems.
- Familiarity: we use industry-standard conventions, tools and languages to make our APIs immediately familiar to anybody using them.
- Flexibility: using a modular, micro-service architecture means that our APIs interact with each other reliably and seamlessly. That makes it easy to customize them to suit your specific needs and payment flows.
The following examples show how our APIs demonstrate these principles and standards in practice.
Restful HTTP resources: to make integrating our APIs into your payment journeys as simple as possible, the first step is to use our root resource to find out what services are available. Once you’ve decided what you need, each action is presented as a Restful HTTP resource that responds to standardized methods, such as POST, PUT or GET.
Consistency of language: we try to use the same language across different services to make our APIs quicker to integrate and easier to learn and use.
Version labelling: to ensure you always have the latest features, we’re constantly issuing new releases and updates. It’s essential that you know which version of a service you’re using, so we’re always clear and consistent about how we label our APIs.
In every API, both the version and service are specified by the media type, which is defined in the Content Type header. In effect, different services and versions use different media types, making it clear which version and API service you’re using.
Documentation and schemas: updating our APIs can mean that previous schemas are no longer supported. To help you out, we make it clear where you can find the necessary information. In brief:
- Details of all changes and release dates are kept with each API’s documentation in a Change Log;
- Schemas for previous versions are always in our
- Documentation for previous versions are held in our
Finally, to ensure resilience when integrating our APIs, you’ll find our definition of non-breaking changes
Hypertext Application Language (HAL): because HAL is an industry-standard, we use it to format our API resources and action links so that they’re compatible with standard libraries.
Using HAL also makes our services simpler. Because it can be read by machines and humans alike, it’s faster to integrate and provides context to our API references, making it easier for human brains to understand what’s going on. Perhaps most importantly, HAL’s ubiquity makes interlinking different API resources consistent and, therefore, much easier. This means that it’s faster to link different Access APIs together to create a more consumable, explorable experience.
Dynamic next action links: we design our APIs to help you flex your next actions in order to optimize them for your specific payment journey. Also, our dynamic next action links come as hypermedia links in order to make the possible payment routes intuitive, clear and easily learnable. This also helps you avoid making common mistakes.
Flexible resources: alongside our guided, dynamic action links, we have built composite action links that let you execute multiple actions in a single call. More generally, using a modular architecture means that, together, our APIs form a flexible toolkit. You can pick and choose services from the kit and combine them seamlessly to suit your specific payment patterns and outcomes. You can also change the services you use, so that you can easily re-tailor your system to suit changing requirements in the future.
We hope that this article has been a useful explanation of the principles we use and the approach we take when developing our suite of APIs. These principles underpin our working practices, so they are unlikely to change. However, they may evolve in the future as we always try to look and think ahead when it comes to our design so that our services continue to provide the maximum possible value to our customers.