What is a Pragmatic API Design and Why it Works?

After you’ve successfully created a fully stabilized data model, it is time to create a public API which can then be used in a web app. However, regardless of the REST API design tool used, once it is released to the public, it is difficult to make any major changes. The only way you can circumvent the situation is to start by using a good design platform and plan ahead. The good news is that the internet is littered with opinions about designing an API and various design platforms because there is no one best way to do things or a standard. Take for instance which is the best format? How does authentication work? Should the API be versioned? In this article, we will attempt to answer a few of these questions.

What is Needed to Design an API?

Pragmatic API Design

A quick Google search for API design will yield a majority of academic answers and articles which use a series of hard to understand explanations and standards. Unfortunately, most of what they talk about is not practical in the real world. So, as an API developer, you need to start by outlining best practices when in the process of coming up with a pragmatic API design. We are not attempting to get you hooked on to a standard but talk about what works. Below we look at a few requirements that the API should meet:

  • It should be developer friendly and easily explored via a web browser.
  • It has to adhere to all the proper web standards.
  • The design has to be intuitive, consistent and straightforward which should make adoption easy.
  • It should be very efficient yet at the same time capable of maintaining a balance with many other requirements.
  • It has to be powerful enough to power the majority of UIs.

Note: since you’re developing an API for developers to use it needs to offer an excellent user experience.

Proper API Documentation

An API is only going to be as easy and good to use as the documentation. So, your documentation should be spot-on. Developers will want to always refer to the document before running any deployment of the API. However, we strongly advise against hiding the PDF behind some sort of authentication since it makes it difficult to access and for search engines to index.

The Use of SSL Certificates

We are staunch believers in the use of developing APIs that use SSL certificates as they are the defacto security standard. Web APIs are accessed by hundreds if not thousands of people each day through a series of networks many of which may be public like in libraries, airports, and shops, etc. So, not every network is necessarily secure, and some may not even encrypt traffic which makes it easy for hackers to look into the information and use it to impersonate people with spoofed credentials.

SSL certificates also guarantee the use of encryption for all types of communication which in turn makes authenticating the system more accessible. So, you no longer have to use the simple access tokens methods for each request to the API.

Non-SSL API access should not be allowed. You never want developers to directly access the requests, and so it should return a meaningful error. Also, poorly configured requests to an endpoint which is not encrypted should also return an error message.


After an API has gone public, it is your job to commit to not changing it without notice. This needs to be documented in the documentation. After all most developers in the API design business aren’t as big as Facebook, and so you can’t take liberties the way they do.

Leave a Reply

Pin It on Pinterest

Share This