Besides algorithms and Systems design interviews in many companies, we might also have a API (Application Programming Interface) design interview. The knowledge of APIs is crucial in the cloud era because Microservices communicate via API.
Therefore, developer teams will often have to align an API contract so that services communicate effectively. Without further ado, let’s explore the main concepts of an API further!
What is an API?
An API, or Application Programming Interface, is like a messenger, allowing different software applications to talk to each other and share information. It serves as a point of connection between two systems, enabling them to interact and exchange data in a standardized way.
Think of it this way: Imagine you want to order food from a restaurant. The menu acts as an API. It provides a list of available dishes, their descriptions, and prices. As the client, you can select what you want to order and communicate your choices to the restaurant. As the server, the restaurant receives your request, prepares the food accordingly, and delivers it back to you. In this analogy, the menu is the API that defines how you and the restaurant can communicate and exchange information effectively.
Similarly, in software, an API defines a set of rules and network protocols that specify how different applications can interact, what data can be exchanged, and what operations can be performed. It simplifies the development process by providing a standardized interface, allowing developers to integrate different systems seamlessly and leverage the functionalities provided by external services or libraries.
What is REST?
REST (Representational State Transfer) is an architectural style rather than a protocol or a standard. It provides a set of principles and constraints for designing networked applications and APIs.
REST is based on a few key concepts:
Resources: In REST, a resource is an entity or piece of information that can be identified by a unique URL, often referred to as a “resource endpoint” or “resource URI.” For example, a resource could be a user profile, a product listing, or a blog post.
HTTP Verbs: RESTful APIs use HTTP verbs (GET, POST, PUT, DELETE, etc.) to perform operations on resources. Each HTTP verb has a specific meaning: GET is used to retrieve data, POST is used to create new resources, PUT is used to update existing resources, and DELETE is used to remove resources.
Stateless Communication: REST is stateless, meaning that each request from a client to a server should contain all the necessary information for the server to understand and process the request. The server does not store any client-specific information between requests. Therefore, it allows for scalability and simplicity in the architecture.
Uniform Interface: REST promotes a uniform interface between clients and servers, meaning the API follows consistent conventions. It includes using standardized HTTP methods, URLs to identify resources, and standard media types (such as JSON or XML) for data representation.
Hypermedia as the Engine of Application State (HATEOAS): REST APIs can include hyperlinks within the responses, allowing clients to discover and navigate related resources. HATEOAS enables a self-descriptive API where clients can dynamically explore and interact with the available resources and actions.
RESTful APIs follow these principles to provide a scalable, stateless, and uniform approach to building web services. It emphasizes simplicity, interoperability, and leveraging the existing standards and infrastructure of the web, making it widely adopted and well-suited for distributed systems.
API Most Used Protocols
We use the following protocols when communicating one service to the other via API. Even though we use the most REST APIs, we have many different APIs. Simply put, an API is a connection point between systems where there is communication. Let’s explore those protocols:
HTTP (Hypertext Transfer Protocol): HTTP is the primary protocol used for communication between clients and servers on the web. It is the foundation of the REST architectural style and is widely supported by various programming languages and frameworks. HTTP provides a simple, standardized way to request and exchange data between clients and servers.
HTTPS (Hypertext Transfer Protocol Secure): HTTPS is the secure version of HTTP that incorporates encryption and authentication mechanisms using SSL/TLS protocols. It ensures that data transmitted between clients and servers is encrypted, providing confidentiality and integrity. HTTPS is essential for secure communication and is commonly used in APIs that handle sensitive data or require authentication.
WebSockets: WebSockets is a communication protocol that enables real-time, bidirectional, and full-duplex communication between clients and servers. It provides a persistent connection for instant data updates and event-driven interactions. WebSockets are commonly used in APIs that require real-time updates, such as chat applications, collaborative tools, or live data streaming.
MQTT (Message Queuing Telemetry Transport): MQTT is a lightweight publish-subscribe messaging protocol designed for efficient communication between devices and servers in IoT (Internet of Things) applications. It is used for sending and receiving messages between devices with low bandwidth and limited resources. MQTT is commonly used in APIs for IoT platforms and applications.
gRPC (Google Remote Procedure Call): gRPC is a high-performance, open-source framework developed by Google. It uses HTTP/2 as the underlying transport protocol and Protocol Buffers for data serialization. gRPC enables efficient and fast communication between services, making it popular for building APIs in microservices architectures.
AMQP (Advanced Message Queuing Protocol): AMQP is a messaging protocol that enables reliable message-oriented communication between applications. It provides a standardized way to send, receive, and exchange messages across different systems and platforms. AMQP is commonly used in enterprise messaging systems and APIs for reliable messaging.
Webhooks: Webhooks are a way for applications to provide real-time event notifications to other systems or applications. Instead of polling or periodically checking for updates, a webhook allows a server to send a POST request to a specified endpoint whenever a specific event occurs. Webhooks are often used for event-driven architectures and integrating systems that require immediate notifications.
SOAP (Simple Object Access Protocol): SOAP is a protocol that allows communication between applications over a network. It uses XML for message formatting and can operate over various protocols, such as HTTP, SMTP, or TCP. SOAP APIs provide a more complex and rigid interface than REST APIs but offer features like built-in security, transaction support, and reliable messaging.
These protocols are widely used in various API implementations and cover a range of use cases, from traditional HTTP-based APIs to real-time communication and messaging protocols. The protocol choice depends on the API’s specific requirements and characteristics and the supported client platforms.
The API design must be defensible
In an API design interview, we don’t need to create a perfect design, but we must be able to defend what we designed. It often happens in real situations as well because we need to agree on an API contract with other teams, and we must tell them why we are creating the API that way.
It’s essential to have a flexible API because external teams will use this API, coupling their code with it. The more situations we plan with the API, the better. We also need to remember that there is no need to fulfill requirements that one day we might have, and we can’t plan too much in the future. Otherwise, the API will get too complicated for nothing in most cases.
API Versioning
API versioning is a practice in software development where different versions of an API (Application Programming Interface) are created and maintained to ensure compatibility and manage changes over time. It allows developers to introduce new features, modify existing functionality, and deprecate or remove certain parts of an API without disrupting existing consumers.
Here are a few common approaches to API versioning:
URL Versioning: In this approach, the version number is included in the URL itself. For example:
https://api.example.com/v1/users https://api.example.com/v2/users
This means that if a user is already using the v1 endpoint, the user can keep using it even if developers created the v2 endpoint. That enables the customer to migrate to the other version whenever it’s convenient.
The version is specified as part of the URL path, allowing clients to access a specific API version.
Query Parameter Versioning: In this approach, the URL includes the version number as a query parameter. For example:
https://api.example.com/users?version=1 https://api.example.com/users?version=2
The version is specified using the “version” query parameter, allowing clients to request a specific version of the API.
Header Versioning: In this approach, the version number is included as a header in the HTTP request. For example:
http Copy GET /users HTTP/1.1 Host: api.example.com Accept: application/json X-API-Version: 1
The version is specified using a custom header, such as “X-API-Version”.
Each version of an API represents a distinct set of functionality and behavior. When making changes to an API, developers typically follow versioning best practices to ensure backward compatibility and minimize disruptions for existing clients. These practices may include:
- Introducing new API endpoints or modifying existing ones while preserving the old endpoints.
- Providing clear documentation and communication about the changes introduced in each version.
- Supporting multiple versions of the API concurrently, allowing clients to migrate to newer versions at their own pace.
- Deprecating and eventually removing outdated or unsupported versions of the API after a certain period.
- API versioning is crucial for maintaining stability, allowing developers to evolve their APIs while providing a consistent experience for consumers and minimizing the impact of changes on existing integrations.
Stripe API
Stripe has their APIs if we want to use their payment services on our websites. Let’s see the example they have for the retrieve customer endpoint:
To understand better how the Stripe API works, read more in their documentation here.
Twitter (X):
To use the Twitter API, first, getting the logged user’s token is required, and then invoking any API method is possible. Let’s explore the tweets count API endpoint:
To further explore the Twitter (X) API, take a look at the full documentation here.
Subscription Platform Recurly:
To use a SaaS platform to manage subscriptions, we have Recurly. Instead of implementing a subscription system, we can use what Recurly provides us.
To better understand how Recurly works, take a look at the documentation here.
Conclusion
We explored an API’s main concepts and clarified what an API really is. Let’s now recap the key points of what we learned about APIs:
- API stands for Application Programming Interface.
- An API defines a set of rules and protocols that allow different software applications to communicate and interact with each other.
- APIs enable developers to access and use the functionality of existing software components or services without needing to understand their internal workings.
- APIs provide a standardized way for applications to request and exchange data or perform specific actions.
- APIs can be used to retrieve data from a server, submit data to a server, or perform operations on a remote system.
- APIs can be categorized into different types, such as web APIs (HTTP-based APIs), library APIs (programming language-specific APIs), and operating system APIs.
- APIs often use common data formats for data exchange, such as JSON (JavaScript Object Notation) or XML (eXtensible Markup Language).
- APIs should be well-documented, providing clear instructions on how to use the API, including available endpoints, request/response formats, authentication methods, and any limitations or usage restrictions.
- APIs can be versioned to manage changes and ensure backward compatibility.
- APIs should have appropriate security measures in place, such as authentication and authorization mechanisms, to protect sensitive data and prevent unauthorized access.
- APIs play a crucial role in modern software development, enabling integration between different systems, fostering interoperability, and promoting the development of third-party applications and services.
