API Development Best Practices: A Guide for Software Developers & Companies • Slash

The term web API generally refers to mutual computer systems communicating over any given network; for example, API services offered by a server, and subsequent API offered by the client such as a web browser. The server-side of the web API equation is a programmatic interface to a defined request-response message system, and is typically referred to as the Web Service. Herein I’d like to introduce some best practices to follow for API development, but first, let’s review the various APIs there are to select from.

Table of Contents

Choosing the Right Approach

If two’s company, and three’s a crowd, then perhaps we should start a team as there are four key ways to make APIs; tomorrow may bring the fifth, we can only hope. I digress, the four methods we will highlight are the following:

SOAP
Rest
GraphQL
gRPC

Let’s begin from the top…

SOAP

SOAP, which stands for Simple Object Access protocol, is an XML-based message protocol that enables the distributed elements of an application to communicate. SOAP can be carried over a variety of standard protocols, including web-related Hypertext Transfer Protocol (HTTP). It was developed as an intermediate language for applications that have different programming languages, enabling them to communicate with each other over the Internet. SOAP is both flexible and independent which allows developers to write SOAP application programming interfaces (APIs) in different languages while also adding features and functionality.

REST

REST is an acronym for Representational State Transfer. It’s a software architectural style that defines a set of constraints for creating web services. It is designed specifically for working with media components, files, or hardware devices. Its key characteristic is its use of less bandwidth which makes it quite suitable for Internet usage.

GraphQL

GraphQL is an application layer server-side technology which was developed by Facebook for executing queries with existing data. It can optimize RESTful API calls, and gives a declarative way of fetching and updating your data. GraphQL can help you in loading data from server to client. It enables programmers to choose the types of requests they want to make.

gRPC

In gRPC, a client application can directly call a method on a server application on a different machine as if it were a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based on the idea of defining a service, and specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a stub (referred to as just a client in some languages) that provides the same methods as the server.

Comparison Chart

	Soap	Rest	GraphQL	gRPC
Message format	XML	JSON/More	JSON/XML	Protobuf/binary
Payload Size	Big	Medium	Small	Smallest
Data Fetching	Might get extra data back	Might get extra data back	Retrieve only data you want	Might get extra data back
Readable message	Yes	Yes	Yes	No
Community support	Widely available	Widely available	Widely available	Limited
Performance	Low performance	Less performance	Medium performance	High performance
Learning curve	Hard	Easy	Medium	Hard
Founded year	1998	2000	2015	2015
Endpoints	Single	Multiple	Single	Single

And the Award Goes to…

For those of you who jumped ahead, I’ll let it pass this time as protocol definitions are not exactly edge of your seat riveting content. I can appreciate you simply want to know which one is best, but let’s give them all the credit they are due.
Alright so if you’re looking for the one with the best security, perhaps you’re designing for a bank or other finance based client business, then SOAP is the one you want. You’ll be working in XML format, focused on server to server communication as there is no mobile integration with your API. Now the learning curve can be a little steep, but you will be rewarded with superior security.
On the flip side of that, if you’re looking for simplicity and the easiest coding path forward, then look no further than REST. You’ll be working with the JSON format for messaging, and you’ll also discover it feels like REST was tailor-made to work for web and mobile apps. Moreover, if you have a strict project deadline to adhere to, REST is great as the simplicity of it ensures no steep learning curve requiring ramp up time for the team initially before coding can get underway.
Now GraphQL is less commonly chosen yet still has its place in the halls of API making protocols. It’s useful for optimizing the response size for mobile and web apps. This of course, will help with speeds on slower connections. As well, GraphQL is handy if you build a microservice architecture and need to merge the sub-graph.
Finally bringing up the rear, we have the formidable gRPC. This little guy will deliver both security and performance in one lean package. You’re likely thinking, “Too good to be true.” Well I can’t say you’re wrong, but honestly when it comes to pure mobile and IoT devices, this is the protocol you want. However, you must accept its limitations such as a chance of a lack of browser support. Remember that the main language support is for C++, Java and so on.
At the end of the day, the most common choice for all developers will be REST and GraphQL. REST is the most popular; however, thanks to the rise of smartphones and proliferation of mobile apps, GraphQL and gRPC have been growing in popularity in the mobile development community. So don’t be hasty to select your protocol or dismiss one you have less experience with… they all play their parts harmoniously!
Now moving on to some best practices for your API development. The following points are a list of things to consider and keep in mind. I have found in my 10+ years of developing that though there is no perfect approach, there are certain boxes you can tick to ensure best practices in developing APIs. So, let’s dive in, shall we?

SSL for Security

SSL as you may know stands for Secure Socket Layer. The clear difference between the URL of an API running over SSL and one which is not is the “s” clearly visible after HTTP. SSL plays a crucial role for security in any API design. It does exactly what you would expect; that is, secures your API making it less vulnerable to malicious attacks. This is a good first step, but other security measures should be taken. Those can include ensuring the communication between the server and client is private, and confirming that anyone consuming the API doesn’t get more than what they request.

API Documentation

An API documentation or specification is like a template of your future docs, the unified language that describes the design of your API, explains how it functions and what to expect from it. There are a few specifications, such as RAML (RESTful API Modeling Language), OpenAPI (formerly Swagger), and API Blueprint.
One of the most useful tools, and free to use, for API documentation is Swagger. Alongside your documentation you have the option to use Postman which can be a solid testing tool in software development to correctly test your APIs; though, keep in mind Postman is a bit pricey to use, yet there is no question to the value it provides.

GraphQL Federation

This only applies to those of you who select to use the GraphQL API type. Federation is a powerful tool with an open architecture for creating a supergraph that combines multiple GraphQL APIs. Each microservice you have in your software gives you a separate endpoint so, the best practice in the case of using GraphQL, is to merge all the subgraphs into one supergraph.
Through using Federation, you can responsibly share ownership of your supergraph across any number of teams. This holds true even if you currently only have one GraphQL API; Apollo Federation is essential for scaling that API as you grow your features, user base and organization.

Regarding CI/CD

Now for a short word on the CI/CD. I personally recommend using a schema registry, and there are three good options available to select from. You may decide which suits the API development best practices for your project.

Apollo Studio

One key point to consider when opting for Apollo is that it’s not open source. Apollo is SaaS run on a cloud platform. There is no setup or maintenance which makes this a very cost effective solution, and your sub-graph should be publicly accessible. If security is of concern and you would like to host the Apollo gateway in your infrastructure, this option may not be the most suitable for you. The enterprise solution version certainly adds powerful options, but comes at a hefty cost and self-hosting is not an option.

GraphQL-Schema-Registry by Pipedrive

On the other hand we have this option presented to us by Pipedrive. It’s open source which is attractive, but there is no SaaS option available. As well, you are limited to self-hosting.

GraphQL Hive

Finally to round out the three, there is GraphQL from Hive. Again this one follows the previous as being open source, but it includes a SaaS option that comes with no setup or maintenance. This makes it a very cost effective solution as you can also host Apollo gateway in your infrastructure. It does include a self-hosting option.

Tests are your Friend so, Test Often

This guide wouldn’t be complete if I didn’t mention testing; for we all know that all best practices require proper testing. API development is no different and you will be best served to factor for frequent testing sessions. This will help you in understanding how each new feature impacts its functionality and subsequently you can then address potential security vulnerabilities. The broad range of available API testing tools covers many scenarios and includes popular tools like Postman, SoapUI, Katalon Studio, and Swagger.
Moreover, one useful method is the BDD (Behavior-Driven Development) approach. This is one of the software development techniques that has emerged from TDD (Test-Driven Development). The principle of BDD testing is that test cases are written in a natural language that is easily readable by non-programmers as well.
One simple example is using Cucumber as a tool of BDD. Consider the following scenario: the user wants to login to the system. The given user launches the login screen. When the user enters the username, password and submits, then a “Login Successful” message appears.

API Observability

Concerning API observability, there are four key points to note herein. Those are monitoring, logging, visualization and tracing. Monitoring is collecting, processing, aggregating, and displaying real-time quantitative data about a system, such as query counts and types, error counts and types, processing times, and server lifetimes. This also includes alerts on anomalies.
Tracing is the ability to follow user requests through the system, even across microservice boundaries, using techniques such as correlation ids.
Logging is collecting system and application logs, in a standard structured format, from servers and services in a cluster. Good logging solutions enforce consistent logging formats for improved parsing of logs. Good logging solutions also include extra details such as correlation ids so it is possible to trace user requests across microservice boundaries.
Visualization is the process of querying for different subsets of data, aggregating as required, and then displaying on charts for easier interpretation of data. Finally, tracing is the ability to follow user requests through the system, even across microservice boundaries, using techniques such as correlation ids.

Purpose: Observability vs Monitoring

Monitoring is about being aware of things we know can go wrong; that is, increases in latency, spikes in error rate, or hosts disappearing and so on. Observability comes into play when unexpected things happen and helps us understand why. Observability is a quality of software, services, platforms, and products that allows us to grasp how systems are behaving. It makes investigating and diagnosing problems easier; the more observable a system is, the quicker we can comprehend why it’s acting up and fix it.
For example, monitoring will tell you whether the system works whereas observability lets you ask why it’s not working. Both are useful tools and should have their place in your toolbox as it is. Remember, you’re only as good as the tools you’re working with, but your best practices can make your APIs polished pieces of coding artwork!