Building developer friendly APIs

Here at Payable we’re trying to build the world’s best APIs to make payments and report on money movement.

APIs are the key ingredient in scaling a technology company's engineers and clients. A developer friendly API can help engineering teams benefit from each other’s work without ever needing to schedule a meeting. These teams can be both within and outside the company. By taking this approach a front end engineer can surface any data that exists for a customer without involving the backend teams and a customer could even create their own dashboard in the very same manner.

We’re also among a growing number of technology companies that describe themselves as API first. This means our product and engineering teams focus on API design before anything else. We make all our APIs public, with the appropriate permissioning, so that they all follow the same high standards when it comes to design and documentation. Although for many end users the API will not be the interface they interact with day to day, by investing in our API design this will fuel the growth of applications built upon our API.

Although developers in the last decade have grown used to consuming APIs described as RESTful, many banks still expect their customers to use SFTP to make bank transfers. The developer friendly APIs that we’re building will allow our customers to use the REST software architectural style with the bank of their choice. RESTful APIs use HTTP methods like GET, POST, DELETE to access resources via URL-encoded parameters and tend to use a web format like JSON for data serialisation.

Although we’re writing great quality documentation, we also want to build APIs that are self-documenting as possible. One of the ways we’re achieving this is through HATEOAS (Hypermedia as the Engine of Application State). With HATEOAS, the API provides information about how the client can navigate the API through hyperlinks. For example, a resource about an account would contain a link to get the associated account balance. This way consumers of the API can navigate around the API like they navigate between pages on the web.

How restful is your API?

The Richardson Maturity Model, developed by Leonard Richardson, is one way of describing how RESTful an API is. We’re aiming to build APIs that have a maturity of level 3. The model has three levels:

Level 0

The API uses HTTP as the transport protocol

Level 1

Instead of making requests to a single endpoint. The API consumer sends requests to individual resources like /accounts instead.

Level 2

The consumer uses HTTP methods like GET, POST and DELETE like they’re used in HTTP. For example, if the consumer used the GET method they know that this will retrieve data without affecting the state of any of the resources.

Level 3

This is where the API implements HATEOAS hyperlinks to aid discoverability so that the consumer knows what they can do next and how to make changes to the resource.

API Design - the core of our business

At Payable, we are also using the widely adopted standard of using plural nouns for all resources to make the API as intuitive as possible. For example, when performing a GET operation to /payment-orders you should expect to receive back a paged collection of all your payment orders and /payment-orders/{paymentId} to retrieve a single “payment order” resource.

You’ll often hear that RESTful APIs are stateless. This means that the server does not maintain a session for the user, instead all the contextual information should be in every request’s headers. The advantage of this is that any server in a pool can service a request, avoiding the need to keep users’ sessions synchronised between servers using shared storage. This allows us to scale the number of servers we have in response to user needs in an almost limitless fashion. Another related term is "idempotent" which means when making subsequent identical requests the server will remain in the same state. This is useful because users often have to make a request many times when their Internet connection is unstable. This is particularly important when making payments; nobody wants to make a transfer twice by accident.

We spend a lot of time thinking about performance, we want users to be able to get the information they are seeking with a single request where possible. For example, to make a payment users should have the option to make a single POST request to /payment-orders rather than having to make a POST request to /counterparties first to create a counterparty. By reducing the number of network calls we should speed up our clients’ applications. We also want to give users the ability to add filters/queries to their requests so they can reduce the amount of data returned in a response and in turn reducing the need for them to build their own filtering logic.

In conclusion, although you can get to market faster by making API design an afterthought. By putting in a little more effort and building an API that just makes sense it can become a major asset for your business and becomes a flywheel for growth.