API and API Designs: API Fundamentals

In partnership with

Hello “👋

Welcome to another week, another opportunity to become a Great Backend Engineer.

Today’s issue is brought to you by Masteringbackend → A great resource for backend engineers. We offer next-level backend engineering training and exclusive resources.

Add file uploads instantly with Pinata’s developer-friendly File API

As a developer, your time is valuable. That’s why Pinata’s File API is built to simplify file management, letting you add uploads and retrieval quickly and effortlessly. Forget the headache of complex setups—our API integrates in minutes, so you can spend more time coding and less time on configurations. With secure, scalable storage and easy-to-use endpoints, Pinata takes the stress out of file handling, giving you a streamlined experience to focus on what really matters: building your app.

Start building!

Now, back to the business of today.

In my previous series, I explored everything you need to know and learn about APIs and what API means.

Today, I’m going to start a new series exploring the fundamentals of API where we will discuss the following topics such as HTTP, API Methods, API terminologies, API status codes, and more.

This is coming from my Backend Engineering Hub under the API and API Design section. However, I’m only transferring the knowledge here and breaking it down one topic at a time in this series.

Understanding TCP/IP

When designing APIs, the important building block to understand is the TCP/IP. It stands for Transmission Control Protocol and Internet Protocol. It is a suite of communications protocols used to connect hosts on the Internet.

To fully understand how APIs work and communicate over networks, a fundamental understanding of the workings of TCP/IP is indispensable.

I have created a detailed blog post on “What is an Internet?” explaining the functions of TCP/IP and how it relates to HTTP.

Now the function of the TCP/IP is to provide ordered, error-checked delivery of streams of bytes from a program on one computer to another program on another computer.

These delivery and transmission can be achieved using many protocols provided by TCP/IP such as FTP (File Transfer Protocol), and HTTP (HyperText Transfer Protocol).

Now, let’s explore HTTP and how it makes API possible for backend engineering.

Hypertext Transfer Protocol (HTTP)

The Hypertext Transfer protocol is a protocol that manages the interaction between a web server and a web browser. It provides a set of rules that establishes a communication standard that governs the exchange of requests and responses between the end user's browser and the web server.

After a connection is made following the rules, It is the protocol used for transmitting hypermedia data on the web, such as HTML webpages or JSON from a web API.

HTTP dictates how endpoints are defined, how data should be transferred, and what status codes should be used to convey specific scenarios.

Therefore, understanding HTTP is crucial for properly creating and designing enterprise APIs as it provides the structure for how requests and responses should be constructed and handled.

The screenshot above depicts a simple request and response scenario, this exchange of web transactions is made possible because of HTTP. Therefore, it’s crucial to understand some terms about HTTP.

We are going to explore the following:

• HTTP Versions

• HTTP Methods

• HTTP Status Code

• HTTP Headers

• Cookies

• CORs

• HTTP Caching

HTTP Versions

If you have to design an enterprise API, you need to understand the HTTP version you want to be running on. The versions of HTTP can directly impact how well an API can communicate with other software and systems.

From HTTP/1.0, the initial version of HTTP to HTTP/2 and the latest version HTTP/3, each version brings in improvements in speed, data transmission capabilities, and security.

Selecting the right version for your API can help you improve your API. Here’s a detailed comparison of the different versions of HTTP.

HTTP Methods

HTTP Methods are vital to API Design and you need to learn them. Also, you need to know when to use each one.

Your knowledge of API Design starts with understanding when to use the right HTTP method for the API endpoint you want to create.

Here are some of the common HTTP methods used in API design:

• GET

• POST

• PUT

• DELETE

• PATCH

• OPTION

Each of these methods signifies a different type of request, allowing for various interactions with your API endpoints. Postman already has good content explaining each of these HTTP Methods.

HTTP Status Code

The best APIs return the best API status codes and do not confuse the user. Part of creating a good API Design is using a consistent HTTP status code for each API endpoint.

You need to study all the HTTP Status Codes and understand when to use 4xx, 5xx, 2xx, etc. Explore all the HTTP Status Codes from the official MDN.

HTTP Headers

HTTP Headers play a crucial role in your API Design as it is used to pass additional information between the client and the server. You need to be consistent with the headers required between all API endpoints.

There are lots of built-in headers and custom headers you can pass between requests and responses to both clients and servers. Here’s a list of all the header information you can pass between clients and servers.

Cookies

In API design, cookies play a key role when authentication is needed. They can store session tokens, enabling users to stay logged in across multiple sessions or web pages.

Grasping the role and functionality of cookies is crucial for API design, as it helps maintain user sessions, enhances user experience, and secures user data. Learn more about Cookies.

CORs

Cross-Origin Resource Sharing (CORS) is a fundamental concept in API design. It utilizes HTTP headers to instruct browsers to grant a web application running at one origin access to specific resources from a different origin.

Typically, web browsers block web pages from making requests to a domain other than their own by default. CORS provides a framework that allows you to set server rules defining which cross-origin requests are permitted, offering essential flexibility while maintaining security.

Understanding CORS is key to designing APIs that enable safe and efficient cross-domain communication.

HTTP Caching

HTTP caching plays a crucial role in API design by storing copies of responses to HTTP requests, thereby speeding up subsequent requests. When an API receives repeated requests, it can leverage cached responses instead of processing each request individually, boosting performance and efficiency. The caching process is controlled through headers in the HTTP requests and responses.

Effectively implementing HTTP caching in API design can significantly reduce latency, lower network traffic, and enhance the API's speed and responsiveness.

Learn Why HTTP Caching Matters for APIs.

Now, let’s look at some other important concepts you need to explore to fully be ready to design your enterprise API.

The following concepts listed below are crucial, especially for API Design:

• URL, Query, & Path Parameters

• Content Negotiation

• Basics of DNS

Let’s explore each of them.

URL, Query, & Path Parameters

Designing a clean and consistent API starts with how you name and present the API endpoints (URL).

The URL serves as the foundation of an API, as it identifies the resource on the server. Query parameters are utilized to filter results, sort data, or display specific data fields. In contrast, path parameters act as placeholders for variable data within the URL, enabling customization of the data response.

Mastering the use of URLs, query parameters, and path parameters is essential for developing efficient, scalable, and user-friendly APIs.

Here’s a quick guide:

• Use Nouns to Represent Resources, Not Verbs

  • Endpoint URLs should represent entities/resources (e.g., users, orders) rather than actions. This keeps the API RESTful and aligns with standard HTTP methods (GET, POST, PUT, DELETE).

  • Example:

    • Correct: /users

    • Incorrect: /getUsers

• Use Plural Nouns for Collection Resources

  • When designing endpoints, use plural nouns to represent collections of resources.

  • Example:

    • /books (collection of books)

    • /books/123 (specific book with ID 123)

• Organize URLs into a Hierarchical Structure

  • Group related resources logically using a hierarchical structure, ensuring URLs reflect resource relationships.

  • Example:

    • /projects/123/tasks (tasks belonging to project 123)

• Use Query Parameters for Filtering, Sorting, and Pagination

  • Avoid designing endpoints for every possible query scenario. Instead, use query parameters to filter, sort, or paginate data.

  • Example:

    • /products?category=electronics&sort=price&limit=10

• Include Versioning in the URL Path

  • Explicitly specify the API version in the URL path to avoid breaking changes when upgrading the API.

  • Example:

    • /v1/users

    • /v2/users

There are many best practices to consider but these are the common ones you should always implement.

Content Negotiation

In API design, Content Negotiation is the process by which the client and server agree on the data representation that is mutually acceptable. This allows clients to specify their preferred response format, such as JSON, XML, or HTML. This mechanism promotes flexibility and adaptability in APIs, enhancing their usability.

Effectively leveraging content negotiation is a fundamental aspect of mastering the basics of API design.

However, different APIs require different content negotiation for example:

• GraphQL APIs use GraphQL

• RESTful APIs use JSON

• SOAP APIs use XML

• etc

Basics of DNS

In API design, the basics of DNS (Domain Name System) are a critical consideration. Acting as the internet’s equivalent of a phone book, DNS translates human-readable hostnames into IP addresses that APIs use for communication. This foundational system plays a vital role in the navigation and messaging flow of APIs.

For API developers, understanding DNS is essential, as it can aid significantly in troubleshooting connectivity issues, ensuring secure connections, and optimizing API architecture through more efficient calls. This knowledge enhances overall API functionality and resilience.

API design is a crucial aspect of any software development process. It starts with understanding the core principles of what an API is, how it functions, and the different types of APIs, such as REST, SOAP, and GraphQL. Additionally, mastering API design involves familiarizing oneself with standards and best practices to create powerful, user-friendly, and secure APIs.

This foundational knowledge serves as the groundwork for tackling more complex API design and development challenges, ensuring robust and adaptable API solutions.

That will be all for today. I like to keep this newsletter short.

Did you learn any new things from this newsletter this week? Please reply to this email and let me know. Feedback like this encourages me to keep going.

See you on Next Week.

Remember to start learning backend engineering from our courses:

1. Become a Node.js Backend Engineer is Live

2. Become a Rust Backend Engineer is Live

3. Become a Python Backend Engineer is Live

4. Become a Java + Spring Backend Engineer is Live

Top 5 Remote Backend Jobs this week

Here are the top 5 Backend Jobs you can apply to now.

👨‍💻 SAP Fioneer
✍️ Backend Engineer
📍Remote
💰 Click on Apply for salary details
Click here to Apply for this role.

👨‍💻 AArete
✍️ Backend Engineer
📍Remote, Worldwide
💰 Click on Apply for salary details
Click here to Apply for this role.

👨‍💻 FREE NOW
✍️ Backend Engineer (m/f/d) - Barcelona
📍Remote, Worldwide
💰 Click on Apply for salary details
Click here to Apply for this role.

👨‍💻 FREE NOW
✍️ Backend Engineer (m/f/d) - Madrid
📍Remote
💰 Click on Apply for salary details
Click here to Apply for this role.

Want more Remote Backend Jobs? Visit GetBackendJobs.com

Backend Engineering Resources

1. Backend Engineering Hub

2. All Backend Books

3. Visit our Backend Store

4. Join our Community

5. Backend Engineering Courses

LAST WORD 👋 

How am I doing?

I love hearing from readers, and I'm always looking for feedback. How am I doing with The Backend Weekly? Is there anything you'd like to see more or less of? Which aspects of the newsletter do you enjoy the most?

Hit reply and say hello - I'd love to hear from you!

Stay awesome,
Solomon

I moved my newsletter from Substack to Beehiiv, and it's been an amazing journey. Start yours here.