In this lesson, you will learn how to define the most basic endpoint (the root) in a FastAPI application. Our goal is for you to understand how to create a root endpoint that responds with a simple JSON message. By the end, you should be able to implement and test a basic root endpoint in FastAPI.

An endpoint is a specific URL path where a client can send requests to a server. Think of it as a web address that leads to a specific resource or action on the server. Endpoints are essential in web APIs as they define where and how the server should respond to requests.

For example, an endpoint can be a URL like /users to get user information or /products to retrieve product details. Each endpoint can support different HTTP methods (like GET, POST, PUT, DELETE) to perform various actions.

HTTP methods indicate the desired action to be performed for a given resource.

Common methods include:

• GET: Retrieves data from the server.
• POST: Sends data to the server to create a new resource.
• PUT: Updates an existing resource on the server.
• DELETE: Removes a resource from the server.

A root endpoint is typically the entry point to your API, defined at the path "/". It commonly uses the GET method to provide a welcome message or basic information about the API, serving as the initial access point for users.

Let's see how we implement it!

As you've seen in the past lessons, we begin by importing the FastAPI class from the fastapi module and creating an instance of FastAPI:

Python
Copy to clipboard
1from fastapi import FastAPI
2
3# Initialize a FastAPI app instance
4app = FastAPI()

This instance will be used to define our endpoints.

To define an endpoint in FastAPI, decorators are used to associate a specific path with a function that handles the requests. Here, we use the @app.get("/") decorator to set up a root endpoint that handles GET requests at the path "/":

Python
Copy to clipboard
1# Define the root endpoint with a GET method
2@app.get("/")  
3def read_root():
4    # Return a simple JSON response
5    return {"message": "Welcome to the spaceship management system"}  

Let's break down the code step-by-step:

@app.get("/") - This decorator specifies that the function handles GET requests at the root path "/".

def read_root(): - This function is designed to handle incoming requests. Its name can be anything meaningful but in this example, it logically represents reading from the root.

return {"message": "Welcome to the spaceship management system"} - The function returns a dictionary, which FastAPI automatically converts into a JSON response.

Here's the complete code:

Python
Copy to clipboard
1from fastapi import FastAPI  
2
3# Initialize a FastAPI app instance
4app = FastAPI()  
5
6
7# Define the root endpoint with a GET method
8@app.get("/")  
9def read_root():
10    # Return a simple JSON response
11    return {"message": "Welcome to the spaceship management system"}  

Now let's see how this endpoint will be accessed!

Once we run our server on localhost, the root endpoint will be available at http://127.0.0.1:8000/ or http://localhost:8000/.

When accessed, you should see the following JSON response:

JSON
Copy to clipboard
1{
2    "message": "Welcome to the spaceship management system"
3}

The output above shows the JSON response sent back by the server when the root endpoint is accessed. This confirms that the FastAPI application is running correctly and can return simple JSON responses.

In FastAPI, a status code is part of the response that tells if a request was successful. For GET endpoints, FastAPI automatically returns a status code of 200, which means "OK" or success. You don't need to set it manually.

When you access the root endpoint, you'll get a status code of 200 along with the JSON message, showing that everything worked fine. If something goes wrong, FastAPI will return codes like 404 for "Not Found" or 500 for "Internal Server Error," helping you understand the issue.

In this lesson, you learned how to define the root endpoint in a FastAPI application using the GET method. You also saw how to set up a FastAPI instance and test the endpoint for a simple JSON response.

Next, you'll get the chance to practice setting up endpoints and customizing the response messages. This hands-on practice is crucial for honing your skills and becoming proficient in FastAPI development. Let's build on this foundation and continue exploring more functionalities!