Pragmatic RESTful API — Design Principles

This is nearly impossible that you haven’t come across the term ‘Rest API’ if you have ever thought about getting data from other sources on the internet or you decided to expose the resources or functionality in your project with some internal/external users.

But why APIs? How to make best use of them? In this article, I propose to cover answers to these questions and a lot more in following articles.

Why Rest APIs?

As the world is going through a tremendous digital transformation, It is almost impossible for any organisation to implement their transformation strategy without utilizing the power of application programming interfaces (APIs). APIs are everywhere in our personal lives — whether you are watching YouTube, purchasing something online from Amazon or posting something on Facebook. APIs enable our digital lives.

Organisations are moving towards Micro-services architectures as opposed to having monolithic architectures. Micro-service architecture is revolutionizing the way enterprises build their technical infrastructure and develop new applications. APIs play a crucial role in facilitating micro-services.

Only when you have well-designed APIs as the communications path between services can you truly take advantage of the team scaling capabilities that micro-service architectures offer.

But why is good API design important?

APIs are the face of any application or service. If APIs are designed properly, they can be among a company’s greatest assets, or huge liabilities otherwise. Bad internal APIs presents itself readily: frustrated developers and delayed deliveries. In a public API, the costs are spread across many teams and thereby vastly overpaid. And despite being more costly in total, a bad public API can resist needed improvements.

Designing APIs is easy, designing good APIs is Hard but achievable. It is possible to design great APIs that people will enjoy using and that you’ll enjoy creating as well.

It’s all about Perspective

If you program, you are an API designer. As API designer, you are designing an interface for programmers, probably without even knowing who they are. And whoever they are, they will have the technical sophistication (or at least you will think they have the technical sophistication) to point out every little flaw in your software. Your users are likely to be as critical of your API as you would be of theirs, and will thoroughly enjoy critiquing it.

API designers typically focus on questions like “What does this service need to do?” or “What does this service need to provide?”, while API consumers are focused on “How can I use this API to do what I need?”, or more accurately, “How can I spend the bare minimum of effort to get what I need out of this API?”.

These different questions lead to two vastly different perspectives. As a result, the necessary prerequisite to designing a great API is to shift your perspective from that of the API designer to that of the API consumer. In other words, continually ask yourself the questions you would naturally ask if you were your own consumer. Rather than thinking about what your API can do, think about the different ways it may need or want to be used and then focus on making those tasks as easy as possible for your API’s consumers.

While this may sound easy and obvious, it’s astounding how infrequently APIs appear to be designed this way. Think about the APIs you’ve encountered in your career. How frequently do they appear to have been designed with this perspective in mind?

API design can be challenging but if you follow a couple of design principles, you can pass through with flying colors.

What all API design Principles we have to follow?

Here are a couple of design principles you shall follow in order to produce great APIs.

Easy to use and hard to misuse

When it comes to API usability, the user we care about is the developer who is writing the code that will use our APIs. This means that the language, patterns and conventions of the API should match its user’s world as closely as possible. That would include the tools and programming languages that they use to write code, the industry and organizations they work within and the community and social world they live in. You need to ensure that people can actually use your API and that it works the first time, every time.

We should also care about exposing only the information that is needed to be exposed and in a structure that doesn’t really exposes the internal structure of the object model.

Stateless Design

Data will never be stored in a session. Each request/response should stand on it’s own and have no relation or dependency on each other whatsoever.

Security

Security is obviously one of the most important things to build into your web service, but so many developers make it ridiculously hard to use. As the API designer, you should be offering usable examples of how to authenticate and authorize when accessing your API. This should not be a difficult issue that an end user spends hours working on. Make it your goal that they either don’t have to write any code, or it takes them less than 5 minutes to write it.

Platform Independent

Any client should be able to call the APIs, regardless of how the APIs are implemented internally.

Service Evolution

The API should be able to evolve and add functionality independently from client applications. As the API evolves, existing client applications should continue to function without modification. All functionality should be discoverable so that client applications can fully use it.

Visibility of System Status

Providing more and better information about the system will help developers understand what has happened when they invoke the API, leading to a better development experience.

Consistency and Standards

Consistency is an important part of interface design — changing the rules for how something works is an unpleasant surprise and can lead to frustration. Learning how to use an API really means learning the rules for using the interface. That includes every part of the API, from the message format and query parameters of the interface to the presentation style of the documentation. Every API design decision that you make establishes a rule that your users will learn.

Here are a couple of questions you can ask yourself:

• Is the API consistent in its signature (e.g. URI format, query controls)?
• Is the vocabulary of the API consistent? Do words have the same meaning everywhere?
• Is the documentation and support tooling consistent across all parts of the API? Does the runtime behavior match the documented behavior?

Flexibility

As it is not possible to anticipate every way that users will want to employ your service, and since not every client platform is consistent (i.e., not every platform has very good JSON support, it’s good to have at least some degree of flexibility or tolerance with regard to your input and output constraints.

The most important thing to look at when determining what format your API should output data in is what users of your API would be using the data for and with. Maybe you need to support legacy systems where JSON parsing is not feasible and XML is more desirable, or maybe it makes more sense for you to output data in the CSV format for easy import into spreadsheet applications. Whichever you choose, it’s important to think about your users and their use cases. You can also consider adding support for multiple output formats.

Another important thing is allowing for different ways of inputting variables. So, just like you have a variety of output formats, allow for a variety of input formats as well (e.g., plain POST variables, JSON, XML, etc.). You should at least be supporting standard POST variables, and many modern applications support JSON as well, so those two are a good place to start.

The point here is that you shouldn’t assume that everyone shares your technical preferences. With a little research into how other APIs work, and through dialog with other developers, you can glean other valuable alternatives that are useful and include them in your API.

Documentation

If you want anyone to use your API, documentation is essential. So how do we write good documentation? The relatively easy part is documenting the API methods themselves; i.e., example requests and responses, along with descriptions of each of the elements in both. Fortunately, there are an increasing number of software tools that facilitate and simplify the task of generating documentation. Ideally API consumer should be able to understand requests and responses after spending minimal time reading the documentation.

Wrapping up

Now that we have gone through the most relevant characteristics of a good API design, I plan to dedicate a couple of following articles going deep into each of these points.

Please feel free to share your feedback. I believe we all can learn from each other and bring about a world which is ideal for everyone!