API sandbox: What does ‘good’ look like in a sandbox – a simple example

In our previous white paper, PSD2/API Programmes: Engaging with Techies, we discussed the role of product managers and business developers in API programmes and concluded that it’s time to engage with techies. One way to do this is to provide API Sandboxes to Fintech Developers where they can play, learn about the bank APIs, and approach the development of their Apps in an agile fashion.

By API sandbox, we mean a simple implementation of an API where Developers can submit API requests and receive realistic responses that reflect the real system behaviour.

But what does ‘good’ look like in an API Sandbox? One characteristic to consider is error handling. We’ll explain the importance of good error handling in the sandbox, with two very simple animations.

This is just one characteristic of a ‘good sandbox’. Watch this space for more discussions on this topic.

Understanding a basic challenge that Fintech developers face

Many Payment Service Providers, such as banks, are exposing APIs for the first time due to the need to comply with PSD2 (https://ec.europa.eu/info/law/payment-services-psd-2-directive-eu-2015-2366_en). At the same time, most Fintechs looking to use these APIs are startups who do not have the luxury of massive resources and time, and need to release new integrations as quickly as possible.

In our experience, many Fintech developers struggle with the API documentation provided by PSPs. The documentation often lacks details and can be hard to understand.

This is not a straightforward issue to resolve. It can be difficult to uncover all the knowledge needed to prepare high quality API documentation. Payment products are often old and there may not be a single source that documents all business rules. But Fintech developers need that information.

Then there’s the question of how best to present the information to developers. Most developers don’t like to read through reams of documentation. Information is always best presented in context, at the point where the developer needs the information. That means, it should be embedded within a development environment, and reported to them as they interact with the API. A ‘good’ sandbox will embed the payments processing business rules and present the relevant information to developers as part of the sandbox ‘error handling’.

How do you build a Sandbox with good error handling?

We’ll discuss three approaches:

  • Create a basic sandbox e.g. using open source tooling
  • Create a copy of the production system
  • Create a sandbox with enhanced error handling

Basic Sandbox

A basic sandbox can be built with open source tooling. For example, REST API sandboxes (server stubs) can be created directly from a swagger file using open source swagger codegen. Many API platforms also provide mechanisms to create basic sandboxes.

Advantage : Quick and easy to create

Disadvantage : Poor error handling, so of limited use to Fintech Developers

The following animation shows the type of error response you might get from a basic sandbox when you send in a request. The error in this case is a basic syntax error. But the quality of the error message is poor, just a generic “something bad happened” message. This makes it very difficult for the Developer to fix the mistake. They will need additional help, for example, from your customer support team, thereby increasing your costs.

If you want to improve the error handling, you will need to write custom code, and that then needs to be maintained.

swagger-default-sandbox-error-handling
View animation in full size

Copy your Production System

A second approach to creating a sandbox is to take a copy of your production system, and rely on the error diagnostics provided by the real system.

Advantage : no additional R&D effort

Disadvantages : significant effort to manage, and poor error handling

On the face of it, using a copy of your production system seems like a reasonable approach but consider that:

It is time and cost intensive to manage such a system.

  • This second system, with all its dependencies, will need to be operated, maintained and upgraded.
  • It will need to be configured, and populated with seed data for each new sandbox user.

The error information provided by the system is likely to be very limited.

  • Errors returned from real systems are usually quite terse, and need to be interpreted by teams who know and understand the system. The errors are not designed to be used by external developers.

This approach is often used for UAT (User Acceptance Testing), but usually requires significant communication between the team at the bank, and the Fintech developers external to the bank, to get working.

Sandbox with Enhanced Error Handling

The last approach we consider is creating a sandbox that natively supports enhanced error handling. The following gif animation shows how the error scenario shown in our earlier example can be handled. In this case the Fintech developer gets a clear message that a syntax error has occurred, and the line number of the error is identified. The developer can quickly and easily diagnose the problem without the need for support from bank staff.

The XMLdation sandbox provides good diagnostics on basic syntax errors out-of-the-box. But it is also designed to incorporate high quality error messaging for bank-specific business rules quickly and easily, providing Fintech developers with the information they need, immediately and in context.

xmldation-sandbox-error-handling
View animation in full size

Plug in the power of a dedicated PSP API sandbox

If you are experiencing problems in working with your developer community, or are just getting started on API development for PSD2/Open Banking, we can help you get value out of your PSP API with the XMLdation API Sandbox. Contact us today!

About XMLdation

XMLdation is a global service provider of XML management, end-to-end testing and simulation services for payment-related XML messages.

Our solutions Request a demo today

Stay up to date

Subscribe to our newsletter

Error: message

Result message

Menu