To do that, I had to manually decide the data format, transfer rate, response time, validation, and so on. They are important to ensure the device remains functional while providing status updates to computers. Yet, without a formal architecture, it took me plenty of trial and error before I could allow other developers to use the APIs I built.
These days, you’ll find several API architectures that you can adopt in web and application development. Trust me, they’ll make API design faster, more secure, and less cumbersome than doing so manually.
In this guide, I’ll walk you through common API architectures you can start with and considerations if you decide to build your own.
Table of Contents
- What is an API architecture?
- Core Components of API Architecture
- Types of API Architecture
- How to Design an API Architecture
- Best Practices When Designing an API Architecture
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
What is an API architecture?
An API architecture is a set of rules, standards, and frameworks that web developers use to build, deploy, manage, and scale APIs. You can think of the API architecture as the blueprint that tells you what, how, and where each API should be implemented in web services. Specifically, the architecture provides a clear definition of how API calls interact with databases, functions, and third-party services.
Let’s say you’re building an AI chatbot, which you want to allow other developers to integrate on their website. Without an API architecture, you’ll need several in-depth discussions amongst internal and external developers just to agree on a specific data format.
But if you adopt existing specifications, such as REST, you can focus more on building the business logic and API interaction itself, since the architecture provides a standard for building the API.
Core Components of API Architecture
An API architecture looks like a complex intersection of many software components. Generally, these are what you can expect to find in modern API architectures.
Endpoints
Endpoints are specific locations referenced by the API call. In web development, they’re often represented as a URL. When making an API call, you send requests and data to a specific endpoint. For example, an endpoint that accepts requests for retrieving customer records looks like this: /api/customer/ID025.
Data Layer
The data layer provides ways to store, update, and retrieve information from databases. It bridges the business logic and storage. Let’s say you’re creating an API that lets vendors store customer records. When the API receives the request, it extracts the data, transforms it, and stores it in a database.
Integration Layer
When you’re creating an API, you need access to other services to achieve the desired business outcome. For example, you integrate with payment gateways, authentication modules, legacy systems, and other services so the API users can transact securely. This layer allows your API to exchange data securely and consistently with these components.
Application Layer
This is where you create the business logic that the API serves. For example:
- A payment service must run codes that validate payment details before it approves the transaction.
- The API updates the logs in the respective database for audit purposes.
- The app communicates with other microservices to execute other functions, such as sending push notifications to the customer.
Every process that directly contributes to the API’s business value happens in the application layer.
Presentation Layer
To use an API, developers need to know the exact function, data format, configuration, and endpoint. And that’s what the presentation layer does. You’ll also need to know the maximum size of data you can send or retrieve at any one time.
For example, REST API supports pagination, a method that divides large data into several smaller pages. If you specify page=2&limit=50 in the API call, you’ll retrieve 50 items from the second page of the results.
Authentication and Authorization
Authentication is permitting a specific user or application to use the API you built. Authorization determines the level of access they get. Both, to me, are crucial for strengthening API security.
For example:
- You assign each user an API key, which they use to identify themselves for access.
- You apply authentication methods like OAuth and JSON Web Token (JWT) to regulate API access.
- You use SSL/TLS to provide end-to-end encryption. When applied, the API scrambles the data so that only the legitimate recipient can read it.
Monitoring
The years I spent building software taught me to always keep an eye on API performance. Sometimes, the response rate might drop as more users subscribe to your API. Or, in some cases, bugs in the API result in some dropped or corrupted responses.
Either way, don’t forget to observe how your monitor performs over time. Tracking API calls helps you learn how frequently they’re used, the resources they consume, bandwidth limitations, and other behavioral data.
Versioning
Often, you improvise an API to include new functions, improve security, or address needs you discover through usage. With versioning, you allow new users to access the latest API while maintaining backward compatibility with those accessing older versions.
I used to add a version check command when creating an API for low-level applications. Before an application uses the API, it checks the version. But these days, it’s simpler for web services. For example, if you’re building a REST API, you can include versioning in the endpoint in the URL like this:
- /api/v1/customer/ID025 for version 1
- /api/v2/customer/ID025 for version 2
- /api/v3/customer/ID025 for version 3
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
Types of API Architecture
Over the years, I’ve seen various API architectures introduced to enable developers to build web services more easily. I’ll go through some of the most commonly used API architectures below.
REST
REST API, or RESTful API, uses the representational state transfer architecture, which allows a loosely coupled client and server to exchange data. REST treats every API call as an access to resources hosted on a specific Uniform Resource Identifier (URI). URI is basically a reference to the specific resources. For example, /login provides access to login validations, and /customer contains customer records.
On top of that, REST APIs are stateless. Stateless means the API doesn’t remember the information an application sent after the server completes a request. So, each time you make an API call, you need to provide all the necessary context.
I like to think of REST as sending or loading information to a website. That’s because REST API uses HTTP methods just like web browsers do. When making API calls, you’re actually using GET, POST, PUT, and DELETE methods to exchange data in JSON format.
Today, many web services use REST to design their API architecture. HubSpot, for example, provides developers access to its services with REST. So are platforms like OpenAI, Meta, and TikTok.
gRPC
A remote procedure call (RPC) is a method that allows an application to invoke a function on another application as if they’re making a local function call. gRPC is Google’s implementation of remote procedure call, but in ways that allow language-agnostic communications to happen.
Let’s say your dev team built a backend service for a point of sales in C++, but wrote the terminal application in Java. With gRPC, the developer building a terminal application can use the remote function exposed by the backend without needing to know C++. All they need to do is call functions like make_payment (parameters) in their code.
gRPC, like REST, is designed around the HTTP protocol. However, gRPC provides streaming support on top of a single request-response exchange. Instead of using HTTP/1.1, gRPC uses HTTP/2, which is a faster protocol. If I want to build an API that provides continuous short video updates, I’ll use gRPC for the low-latency function calls it provides.
GraphQL
GraphQL is a query language that you can use to create APIs. It was introduced by Facebook to improve the way its mobile app retrieves news on the feed. Until then, REST API architecture, which many developers were using, required sending complex requests and interpreting equally complex responses.
On top of that, you might need to filter the responses to get the relevant, specific data. And in that process, you often ended up with lots of unneeded data. But GraphQL changes that.
GraphQL is a very efficient method for retrieving information. With GraphQL, you can query specific data, such as SalesForNotebook, and receive nothing more than the data you described. For me, that’s a great way to reduce bandwidth usage.
SOAP
SOAP, which stands for simple object access protocol, is an API architecture that was introduced in the 1990s. Back then, SOAP primarily supported enterprise applications, which required a more structured and established method of data exchange.
With SOAP, applications structure their requests in XML and receive responses in the same format. Compared to REST, SOAP is more rigid, slower, and harder to scale, mainly because of the size of the payload required in the data exchange.
While SOAP uses HTTP for transferring data, it can also operate on other protocols, such as SMTP. This means that you can develop APIs for applications that need to exchange data reliably across different layers of the networking architecture. SOAP, in my opinion, is a decent choice for building enterprise APIs that require strong corporate security and governance.
How to Design an API Architecture
API architecture design is similar to software development. In fact, I’ll say that API architecture design is software development with a twist. Many stages that are practiced in software development still apply, along with several API-specific activities.
1. Define the API’s purpose.
First, determine the type and purpose of your API because every API requires different approaches, security measures, resources, and other considerations.
For example, if you’re architecting an API for querying ecommerce product data, you’ll need to provide for scalability, traffic balancing, and rate limiting. Conversely, if you want to build an API for internal use, you might want to pay more attention to confidentiality, compliance, and interoperability.
2. Design the data model.
An API, at its core, is layered over a data storage. Therefore, before your team works on other API components, spend time establishing the data model. Ask questions like:
- What’s the expected storage growth rate over time?
- What schema structure does your API use?
- Which fields does each dataset or table need?
- What are the relationships between various data types?
- How do you regulate access to stored data?
Also, consider data processing, data transformation, and other data manipulation requirements, particularly if you’re building an API for machine learning services. For example, you need to transform raw data into structured datasets before you use them for data warehousing.
Trust me, the last thing you want when working on an API is to rearchitect your database because you’ve overlooked critical data fields.
3. Create API endpoints.
By now, you should have a better idea about which API architecture to use. Regardless of your choice, the next step is to create the API endpoint and request-response format for each. Usually, if you’re creating a REST API, you need to decide the type of messages, HTTP status, and error response structure.
For example, the endpoint PUT /products expects a message consisting of the product name, price, stock, and other transaction details. It should validate that the information is in order before storing them into the database.
Note: When creating API endpoints, consider the message size that client applications can support. From my experience, it’s better to allow the client to negotiate the response size to accommodate a more diverse device range.
4. Implement authentication/authorization.
Make sure your dev teams apply methods for controlling who can access the API and how they use it. As I’ve shared, you can generate API keys for respective users. Additionally, I recommend using OAuth or JSON Web Tokens (JWT) to add layers of security.
5. Prepare documentation.
I can’t stress this enough: Documentation is crucial when designing an API architecture. A comprehensive documentation allows other developers to use your API easily. From the documentation, they’ll know the exact message structure, command, response, and error codes when interacting with the API.
If you want to know what a good API documentation looks like, check out HubSpot’s API Reference Overview. From a developer’s point of view, it’s clear, descriptive, and easy to understand.
6. Test the API.
Next, put the API to the test. Make sure that the API accurately interprets, processes, and responds to each request-response sequence you’ve created. For example, if an API call is meant to return the weather in London, it shouldn’t report on Paris or elsewhere.
Functionality aside, you also need to assess the API for stability, bugs, and other technical issues. If it crashes after responding to several requests, your dev needs to investigate more deeply to iron out the root cause.
7. Optimize for production.
By now, you’ve got an API that works well in the lab. But don’t be too hasty to deploy it yet. From my experience, the real-world environment brings challenges you don’t see in a lab.
So, be prepared. Use these measures so your API can perform consistently when exposed to the uncertainties in production.
- A rate limiting mechanism prevents excessive API calls that can overload the server.
- A load balancer distributes requests to servers with capacities during peak usage.
- Error recovery allows the API to resume operation even when it faces critical errors.
- Caching reduces repetitive API calls for the same request, which helps you optimize resources and reduce operational costs.
8. Deploy and monitor.
Once you’ve done the preparation and ironed out all bugs, deploy the API. This isn’t a one-off process, though. After your API goes live, monitor for usage issues, technical problems, or other challenges that users might face. From what I’ve gone through, it might take several rounds of refinement before your API performs consistently.
If you need more help with API, download our free API guide here.
Best Practices When Designing an API Architecture
There’s a world of difference separating a functional API and an API architecture designed for scalability, security, and effortless use. Below, I share several tips that I picked up throughout my years building software and API.
Be consistent.
Developers thrive in consistency, and that includes API architecture. Use standard naming, conventions, and patterns across all API elements. For example, in REST API, using a noun to represent a specific category is a norm (/users, /product).
But if you’re creating an API with gRPC, you can maintain consistency by naming your functions in a specific way, such as using a verb+noun hierarchy (GetUsers, SetProducts).
Provide comprehensive error handling.
Don’t just return error codes, but provide sub-code or a description that explains the error. This will help API users troubleshoot issues they face without going through unnecessary investigative steps.
Gather stakeholder feedback.
Involve software developers, product managers, potential API users, and other stakeholders throughout the entire implementation. Otherwise, you might overlook critical requirements that will demand more effort to fulfill down the line.
Build your API with the right architecture.
Now that you know the common types of API architecture you can work with, you can start planning on how you want to expand your web services with an API. While the REST architectural style is highly popular for modern web design, there are cases where opting for other architectures makes more sense, technically and business-wise.
When you architect the API, be mindful of the steps I’ve shown, particularly on data modeling, endpoint operation, and ample testing. They’re crucial in ensuring your architecture supports a functional, responsive, and scalable API.
Editor's note: This post was originally published in February 2023 and has been updated for comprehensiveness.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
![How to get a YouTube API key [tutorial + examples]](https://53.fs1.hubspotusercontent-na1.net/hubfs/53/%5BUse%20(1)-4.webp)
