DEV Community: Embold Technologies

Taking a Look at REST API Design Patterns

Embold Technologies — Wed, 19 Aug 2020 12:36:39 +0000

We know what webservices are, and that there exist multiple types of webservices. But the main type is REST—although it is most often used in the context of HTTP, REST is an architectural design pattern, not a communication protocol.

In this article, we talk a bit about useful and intuitive design patterns in RestFul webservice API architecture. In general, design patterns are formalised best practices that a programmer can use to solve common problems when designing an application or system. Below are different elements of design patterns for REST architecture.

REST architecture style constraints: There are design rules that are applied to establish the different characteristics of the REST architectural style, which are referred to as REST constraints:

Client-server
Statelessness
Cacheable
Uniform interface
Layered systems

Goals of RESTful API design: Restful APIs should be straightforward, unambiguous, easy to consume, well-structured, and most importantly, accessible with well-known and standardized HTTP methods.

API design goals:

Affordance:

Affordance is the possibility of an action on an object or environment. An API with clear perceived affordance allows the developer to understand its purpose and to use it seamlessly inside the Cybernetic Environment it was designed for.

Loosely coupled:

In Restful APIs, multiple clients are connected to the same backend server. So when internal representation of a server is changed, it should not affect API consumption at the client side. In a loosely coupled design, APIs are independent, and modifications in one won't impact the operation of consumers. Within an API, the components get added, modified, or replaced. However, the loose coupling approach offers clients better flexibility and reusability of APIs while its elements are added, replaced, or changed. Well-designed APIs exhibit loose coupling and well-composed functionalities across service boundaries to maximize scalability factors.

Leverage existing web architecture:

RESTful APIs should use HTTP as a transport layer since the infrastructure, server and client libraries for HTTP are widely available already. RESTful APIs should take advantage of HTTP methods, or verbs, such as GET, PUT and POST.

RESTful API Design Patterns: API design patterns provide a description or templates to solve specific, recurring API design problems that any software architects and API designers would like to adopt in their API designs.

Statelessness:

Communication between client and server should be stateless, means that every client request contains all the information necessary for the server to process the request. So there is no global state thereby reducing the complexity of the server.

The good news is that some Restful web frameworks provide out-of-the-box implementation for Statelessness. For example: Spring Boot's REST API framework.

Content negotiation:

Content-negotiation is a mechanism or process that services and clients can select as their resources representation format for their communication and handshakes during their usual course of communication.

HTTP specification comes up with a set of standard headers, through which the client can get information about a requested resource and carry the messages that indicate its representations.

So, for content negotiation, REST services need to use HTTP headers; that is, when the client makes requests, it includes the accepts header, the list of file types that the client and server can handle with no additional steps to the client requests, the server processes, and replies.

E.g. In Java we can use produces property in @GetMapping annotation

@GetMapping(path="/investors/{investorId}/stocks/{symbol}", produces={MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})

URI Templates

It is always the case that the client may need to include some additional information in their request, and how the server lets the client include that information about resources in the URIs. Server-side developers require the ability to describe the layout of the URIs that their services will respond to. So we can use URI template. URI templates provide a way to describe a set of resources as variables.

E.g. If there are multiple resources,

People: https://swapi.co/api/people/

Planets: https://swapi.co/api/planets/

Films: https://swapi.co/api/films/

Species: https://swapi.co/api/species/

We can use simply https://swapi.co/api/{resource_id}/ as a URI template

The @PathVariable annotation provided by Spring Boot helps us implement the URI template pattern in our code seamlessly.

Design for Intent

Design for intent is a method that expresses the different relationships between objects so that changes to one object automatically propagates changes to others.

In a RESTful API world, the API should be developed to ensure they meet the requirements of the desired use cases provided and faced by users, but without exposing the internal business objects. Design for intent is a strategic design pattern that's intended to influence or result in specific and additional user behaviours.

Pagination

When there are multiple rows of data available then APIs should give the requested data in batch wise (Pagination).

Pagination is a concept that helps in serving only part of the data as a response, however, with information about how to access all the data from the server, page by page, without much load and high computation for the server to serve the whole data.

E.g. xxx.api.com/students?page=2.

There are three variants of resource representation ways of pagination:

Offset-based
Time-based
Cursor-based

Discoverability:

Discoverability is very important factor in API designing, helping developers figure out programmatically whether the site that's being accessed has an API enabled or not will be the most critical responsibility of the API.

Using following two ways we can ensure discoverability of API for developers,

By valid HTTP methods:

When clients call REST services with invalid HTTP methods, the response of that request should end up in the 405 HTTP error code; that is, 405 Method Not Allowed. In addition to the error code, the response header should provide flexibility to the client to find the supported methods that allow headers in its response.

By providing the URI of the newly created resource:

Including the URI as part of the location header as the response to the newly created resource is another method of discoverability. The returned URI as a location will be available through GET.

In Sprint boot it gives out-of-the box solution for discoverability E.g. Using @GetMapping annotation

Unicode:

A simple yet powerful way to make API support multiple languages is to enable the API to support Unicode.

Unicode is an encoding standard that support an international character set. It has a unique number for every character across multiple languages including Chinese, Korean, and Arabic and their scripts. The unique number makes almost all characters identifiable and accessible across platforms, programs, and devices.

API design principles:

In general, the following standard guidelines should be followed while designing high-quality Restful APIs.

Ubiquitous web standards
Flexibility
Standardization
Optimization
Granularity
Sandbox or playground

This should be an excellent starting point for anyone who wants to get their hands into RESTful services, with not just the basics, but essential patterns as well. The enemy of design patterns are anti-patterns, which seem sounds but are counter-productive when executed. Unfortunately, anti-patterns are hard to detect. Read more about how a free static analyser like Embold detects up to 30 structural design issues in Java programming. You can check out my other article on anti-patterns as well.

Did you find this useful? Please comment.

The Silent Villains of the Coding Universe: A Review of Common Java Anti-Patterns.

Embold Technologies — Tue, 11 Aug 2020 16:33:59 +0000

Anti-Patterns seem harmless but lead to error-prone solutions and make your code unmaintainable in the long-run.

For those who aren't familiar with the term ‘anti-pattern,’ it may sound like frivolous jargon or a throwaway catchphrase, but for those in the know, it’s a little more sinister than that.

First coined by famed American programmer and prolific author in the programming literature space – Andrew Koenig – anti-pattern is the antithesis of the popular and positive ‘design pattern,’ created by programmers as a reusable solution that can be deployed to solve recurrent problems.

Today, anti-patterns represent a solution to a programming issue that seems to work when taken at face value but causes problems when executed. Simply put, anti-patterns are patterns that look sound but are counter-intuitive in practice—they result in unmaintainable and error-prone solutions.

Usually, anti-patterns emerge over a period of time when new functionality is added incrementally without a focus on continuous refactoring. Maintenance of code by different developers over a period of time often compounds the problem.

Here are some examples of anti-patterns that tend to crop up in Java-based programming:

God Class: A god class is a class of code that executes multiple functionalities that are typically unrelated to each other. This creates needless complexity in the methods being run and results in a class that becomes too critical to the overall functionality of the program. Because this one class affects so many others, you have to be exceedingly careful when it comes to refactoring this class. Since a god class doesn’t follow one of the most basic tenets of programming whereby a big problem is deconstructed into several smaller problems and then solved individually, it results in a code where any small change could have a domino effect on the entire system. A single class with too many functions, excessive amounts of data, and too many methods is a classic example of a god class.

Global Breakable: Typically a structural component with an excess amount of outgoing dependencies is referred to as a global breakable. This type of anti-pattern is in constant need of maintenance as any change made to the components it is dependent on will result in a need for a change to this component as well. This is a sign of weak code and a system that is missing modularity.

Global Butterfly: On the opposite spectrum of the global breakable is the global butterfly. This structural pattern denotes an object that has a number of dependents that are much higher than is advisable. Whether these dependents come in the form of classes, inner classes, interfaces, or packages, all of these result in a global butterfly situation. The drawback of having a global butterfly as part of your code is that it becomes impossible to change this code outright, and even small alterations to this component become a delicate operation that could have a wider knock-on effect.

Shotgun Surgery: If you have seen a class or method that has a disproportionately high number of incoming couplings, then that is a classic example of what is known as the shotgun surgery anti-pattern. A single change in this class will affect all the methods that call into it. This means that everything from testing this class to refactoring and maintaining it becomes needlessly complex. This class becomes critical as so many methods are dependent on it, even though it may not have as imperative a role to play in isolation.

Feature Envy: Logically, it is prudent to package data together with the processes that require it. Feature Envy is an anti-pattern that works against this approach. In Feature Envy, the method is linked with a class outside of the package it is a part of. This results in a situation where the importance of a class suffering from Feature Envy is simply reduced to that of a Data Class. Or worse, the method in question may use data from both its own class and from an external class as well. In this case, its functionality becomes even more complex causing the need for extra care during refactoring. You need to put the data and the code that references it together in one package, without any external links to ensure that you avoid feature envy.

Dispersed Coupling: If a class features methods that are reliant on operations that are spread across a number of different operations in various different classes, you have what is known as a dispersed coupling on your hands. Because of this, if a change is made in the dispersively coupled method, changes will also be required in all the classes it accesses.

Global Hub: This is a commonly found component where you see a high number of global dependents attached to it, and the component in question also being globally dependent on an excessive amount of other components. Too many outgoing and incoming dependencies see the same component become both a global butterfly and a global breakable. This results in a situation where the code becomes too complicated to follow, and maintenance becomes a major issue as well. A global hub will also result in a situation where the reusability of a module is broken.

Brain Method: As is indicated by its name, a brain method is the type of anti-pattern that carries out a majority of the functions in its class. Rather than these functions being distributed across several methods, having them included within a single brain method sees the requirement for too many conditional branches. The brain method is like a scaled-down version of a god class, and as such, suffers from similar issues. The code that makes up a brain method is too long and a little too complex, making it difficult to understand, and almost impossible to reuse. The presence of a deep nesting situation with the high number of conditional branches means that it needs to be tested more thoroughly than usual as well. Furthermore, the presence of multiple functions in one method will result in a situation where the method is reliant on a high number of temporary variables, making it more susceptible to errors.

These are just a few examples of the many anti-patterns that can throw a wrench in your code, causing further delays as your DevOps team identifies and fixes the issues created as a result of their presence. Anti-patterns are classic examples of how not to do things, and since they often masquerade as working code, sniffing them out can be quite the challenge. You can’t really know you’re doing something wrong until your mistake is pointed out to you, right? This is where static code analysers can help. Advanced static code analysis tools can detect these with ease. Read more: https://docs.embold.io/anti-patterns/#what-are-anti-patterns

Generally, utilising a static code analysis tool will ensure that your programming resources are consumed for the right reasons. You can focus on development, innovation, expansion, and progress rather than on putting out fires, troubleshooting, going back and constantly re-checking code, and fixing all the issues that will crop up thanks to anti-patterns.