A Guide to APIs (Collection of Questions and Answers for Beginners)

This article is a collection of the questions that came up when I first learned about APIs. Each question is followed by an answer which can guide you to a better understanding about APIs.

Alright, let’s delve into the questions now!

1. What is an API?

API stands for “Application Programming Interface”. It’s a way for applications to communicate with each other.

2. What exactly is an API? Why is it named as Application Programming Interface?

The term “Application” refers to any software application or program, that uses or is used by the API. It could be a web application, mobile application, or even another API.

The term “Programming” refers to the act of writing code. APIs are used in programming to define how software applications should interact with each other.

The term “Interface” means to interact with or connect with something. Interface here refers to a set of rules that define how applications should interact. The rules show what features are provided by the API and explain how to use them. The features usually include specific URLs where request can be sent (endpoints), request methods, data formats, parameters, response codes, error messages, and number of requests that can be made in a certain time (rate limiting).

So, an Application Programming Interface is a set of rules and protocols that allows software applications to communicate with each other.

3. How do APIs Work?

APIs are like the waiters in a restaurant. The customer gives an order (the request) to the waiter (the API), who then communicates the customer’s order to the kitchen (the server) and serves the food (the response) to the customer’s table.

APIs operate through a request and response cycle. A user or another system makes a request for data by interacting with an application. The request is sent to the API, which retrieves the data from the server and returns it to the user.

4. Are there any categories of APIs that I need to know before I use them?

From the What is an API? article, there are many different types of APIs and ways to categorize them. For instance, we can categorize APIs by who has access to them.

We can also categorize APIs according to their architectural style. These most frequently used architectural styles are:

• REST

REST (Representational State Transfer) is an architectural style that provides standards for communication between computer systems on the web, making it easier for systems to interact with each other. REST is the most popular API architecture for transferring data (sending and receiving information between different systems) over the internet due to its simplicity and scalability.

REST is stateless, meaning that each request contains all the information needed to process it, and the server does not store any session data. This allows for easy load balancing (distributing the work among different servers) and fault tolerance (continuing to work even if something goes wrong), because any server can handle any request.

In a RESTful service (a service that implements the REST architecture), data are accessible via endpoints, and operations are performed on those data with standard HTTP methods such as GET, POST, PUT, and DELETE.”

• SOAP

SOAP stands for Simple Object Access Protocol, uses XML to transfer highly structured messages between a client and server. A highly structured message follows a specific format and rules for its content and structure. A highly structured message can be validated, parsed, and processed by different applications or systems that understand the same format and rules.

SOAP is often used in enterprise environments or legacy systems, and while it includes advanced security features, it can be slower than other API architectures.

• GraphQL

GraphQL stands for Graph Query Language, is an open-source query language that enables clients to interact with a single API endpoint to retrieve the exact data they need, without chaining multiple requests together like a REST API.

GraphQL returns exactly what a client asks for, nothing more, nothing less. This approach reduces the number of round trips between the client and server, which can be useful for applications that may run on slow or unreliable network connections.

GraphQL is also stateless just like REST API, the server does not save response history between requests.

• Webhooks

Webhooks are essentially a way for applications to communicate with each other automatically. Webhooks are used to implement event-driven architectures, in which requests are automatically sent in response to event-based triggers (whenever a specific event occurs). For example, in a blogging platform, an event trigger could be the publication of a new blog post. When this event occurs, it triggers the webhook, which sends an HTTP request to a specified URL. The request contains data about the event (like the blog post title and author), which can then be used by the receiving system to perform an action (like sending a tweet or updating a database)

5. Tell me about some common API terminologies!

Here are some common API terminologies:

• API Call: The process of sending a request to your API after setting up the right endpoints.
• API Economy: The exchange of value between a user and an organization. It enables businesses to leverage APIs from other providers to power their own apps (this allows them to provide more features and services without having to develop everything from scratch).
• API Endpoint: A specific URL where an API can be accessed, It’s the URL of the server or service. When APIs interact with other systems, each touchpoint of interaction is considered an endpoint.
• API Gateway: An API management tool that serves as an intermediary between the client and a set of different backend services.
• API Integration: A process that connects two or more applications to exchange data between them and connect to the outside world.
• API Keys: A unique identifier that enables other software to authenticate a user, developer, or any software application that is making the API call.
• API Lifecycle: The process of managing an API throughout its entire life, from creation to retirement.
• URI (Uniform Resource Identifier): A string of characters that identifies a name or a resource on the Internet. This could be a page of text, a video or sound clip, a still or animated image, or a program.
• URL (Uniform Resource Locator): A specific type of URI that describe how to access a resource over a network using specific protocols. URL specifies the location of a resource on the web.
• Resource: Data that can be accessed and manipulated through the API.
• Request: Action of asking for a resource or data. In APIs, a client (like a web browser) sends a request to a server, and the server returns a response.
• Response: Data that the server sends back to the client after receiving a request
• HTTP Methods: Actions that can be performed on an API resource.

6. What is HTTP?

HTTP (Hypertext Transfer Protocol) is a protocol used for transmitting hypertext over the internet. Transmitting hypertext refers to the process of sending hypertext from one system to another. Hypertext is a format of text which contains links (hyperlinks) to other documents or web pages. Hyperlinks are elements in a web page that allow users to navigate to another web page or resource by clicking on them.

HTTP is the foundation of any data exchange on the web and operates as a client-server protocol. A client sends an HTTP request to a web server, the server receives the request, process the request, and then returns an HTTP response (output) to the browser. The client receives the response.

An HTTP request consists of several parts which have a crucial role in telling the server what resource is being requested, how the client wants to interact with that resource, and any additional data the server might need to fulfill the request. This is what the structure of an HTTP request looks like:

POST /path/to/resource HTTP/1.1
Host: www.example.com
Content-Type: application/json
Content-Length: 123

{
  "key": "value"
}

Now, let’s break down each part:

• Request Line: The first line is the request line, which contains the HTTP method (POST), the path to the resource (/path/to/resource), and the HTTP version (HTTP/1.1).
• Headers: After the request line, we have the headers. Each header is on a new line and has a name and a value. In this example, there are three headers: Host, Content-Type, and Content-Length. The Host specifies the domain of the server, Content-Type specifies the media type of the body, and Content-Length indicates the size of the body.
• Empty Line: After the headers, there’s an empty line. This line is used to separate the headers from the body. While this might seem like an unnecessary detail, the empty line is a crucial part of the HTTP protocol’s structure. If this line is missing or incorrectly formatted, the HTTP message may not be correctly interpreted by the server or client.
• Body: The last part is the body, which contains payload which is the data we want to send to the server. In this case, it’s a JSON object with a key-value pair.

The exact structure can vary depending on the specifics of the request. For example, a GET request might not have a body.

7. What are the most commonly used HTTP methods?

These are the most commonly used HTTP methods:

• GET: This method is used to retrieve data from a server. It requests a representation of the specified resource and should only retrieve data.
• POST: This method is used to send data to a server to create a new resource. The data sent to the server is stored in the request body of the HTTP request.
• PUT: This method is used to update a current resource or create a new resource if it does not exist. The request body contains the data to be updated.
• DELETE: This method is used to delete a specified resource.

8. Is every request guaranteed success?

When a client makes a request to an HTTP server, the server must notify the client if the request was successfully handled or not. HTTP accomplishes this with five categories of status codes:

• 100-level (Informational): server acknowledges a request.
• 200-level (Success): server completed the request as expected.
• 300-level (Redirection): client needs to perform further actions to complete the request.
• 400-level (Client error): client sent an invalid request.
• 500-level (Server error): server failed to fulfill a valid request due to an error with the server.

As you can see the 400-level and 500-level are for error status. Here are some common error status codes:

• 400 Bad Request: client sent an invalid request, such as lacking required request body or parameter.
• 401 Unauthorized: client failed to authenticate with the server.
• 403 Forbidden: client authenticated but does not have permission to access the requested resource.
• 404 Not Found: the requested resource does not exist.
• 412 Precondition Failed: one or more conditions in the request header fields evaluated to false.
• 500 Internal Server Error: a generic error occurred on the server.
• 503 Service Unavailable: the requested service is not available.

9. What is fetch()?

The fetch() is a method from Fetch API which used to request data from a server. The Fetch API provides a JavaScript interface for accessing and manipulating parts of the HTTP protocol, such as requests and responses. The fetch() is promise-based, making it easier to use in asynchronous operations.

If you want to learn more about fetch() you can visit this article, “What is AJAX, XMLHttpRequest, fetch() and Promise?”

Here’s a basic example of how fetch() works:

fetch('https://api.example.com/data')
    .then(response => response.json())
    .then(data => {
      console.log(data);
    })
    .catch(error => console.log('Error:', error));

Here’s a breakdown of what each part of the code is doing:

• fetch('https://example.com/data'): In this example, the fetch() function is used to send a network request to the URL ‘https://example.com/data’. This returns a promise that resolves to a Response object, representing the response of the request.
• .then(response => response.json()): This method is called after the request is completed. The then() method handles the fulfilled promise from the fetch() call. Inside this method, we use .json() to parse the result as JSON.
• .then(data => { console.log(data); }): This code is called after the JSON data is available. This data is then logged to the console.
• .catch(error => console.log('Error:', error)): This code catches any error that might occur during the fetch() request or the subsequent then() operations. If an error occurs, it is logged to the console.

10. Does every API use HTTP as protocol for communication?

HTTP is the most common protocol used for web APIs, such as REST, GraphQL, SOAP, and Webhooks, serving as the underlying protocol for communication. However, there are also APIs that do not use HTTP as their protocol, here are some examples:

• Database APIs: These APIs allow applications to communicate with a database directly, using a database-specific protocol rather than HTTP.
• Operating System APIs: These APIs provide functions and procedures that applications can use to interact with the operating system. They do not use HTTP, but rather, they use system-level protocols.
• Library or Framework APIs: These APIs provide pre-defined functions, methods, or classes that developers can use when building applications. They operate within the same memory space as the application, so they don’t use HTTP.
• Hardware APIs: These APIs allow applications to interact with hardware components, such as a GPU or a printer. They typically use low-level protocols that are specific to the hardware, not HTTP.
• SOAP APIs: While SOAP APIs can use HTTP as a transport protocol, they can also use other protocols like SMTP (Simple Mail Transfer Protocol) or even FTP (File Transfer Protocol).

The choice of protocol depends on the specific needs of the API and the system it’s interacting with.

Well, these questions are just the tip of the iceberg when it comes to APIs. There’s so much more to discover and learn, but I hope this article has answered some of your questions about APIs.

If you want to learn about how to use an API with REST and GraphQL, you can visit this article “Learn How to Use an API with REST and GraphQL”.