# Postman
Download Postman: https://www.postman.com/downloads/ (opens new window), create an account and log in.
Postman is software to test APIs. It was initially released in 2012 by Abhinav Asthana and has a strong range of free core functionality.
# Using Postman
# Request 1
From the workspace: open a new tab to create your first API request.
Enter the following link in the 'search bar', make sure the HTTP method in front of the link is 'GET' and press 'Send':
https://v2.jokeapi.dev/joke/Programming
Watch the result in the bottom screen section.
The result is that a random IT related joke is shown.
# Request 2
Enter the following link in the 'search bar' and press 'Send':
https://api.nationalize.io?name=michael
Use your own first name in the link (so replace michael with your own first name).
The result is JSON code containing probable countries (by country code).
# HTTP status codes
Every time that a request is made towards an API, the server will not only reply with a response body... a HTTP status code is also given in the response. This status code will always be given back as a reply to the request and indicates whether the request could be answered properly. In our Postman request, the HTTP status code can be seen as indicated in the screenshot:
The first digit of each three-digit status code begins with one of five numbers, 1 through 5; you may see this expressed as 1xx or 5xx to indicate status codes in that range. Each of those ranges indicates a different category of server response. The following ranges exist:
- 1xx - Informational - The request was received and the server will continue processing
- 2xx - Successful - The request was successfully completed
- 3xx - Redirection - The request was received, but there's a redirect of some kind
- 4xx - Client error - The request cannot be fulfilled (e.g. because of bad syntax)
- 5xx - Server error - Even though the request appears to be valid, the server could not process it correctly
Each status code also comes with a description.
# HTTP status code 200: "OK"
Let's start with the most common status code: 200. This status code means that the request was successful and everything went 'according to plan' from the point of view of the server on which your API is running. The textual description of this status is "OK". Status code 200 is the default status that is sent back by FastAPI when nothing is out of the ordinary.
TIP
When your API is running, uvicorn will log some information about the requests that have been made. From these logs (that will appear in the terminal) you can see which endpoints were addressed with which method, as well as the status that was returned. For example:
# HTTP status code 403: "Forbidden"
HTTP status code 403, commonly known as "Forbidden," is used to indicate that the server understood the request but refuses to fulfill it due to insufficient permissions or authorization credentials. Essentially, it means that the server has recognized the client's request but is refusing to process it because the user does not have the necessary permissions to access the requested resource.
# HTTP status code 404: "Not Found"
The HTTP 404 "Not Found" response status code indicates that the server cannot find the requested resource (pay attention: it does not indicate whether the absence is temporary or permanent). Status code 404 is given back by FastAPI by default if it cannot find the requested endpoint, but can also be programmed in the API when a record in a database can not be found for example.
# HTTP status code 422: "Unprocessable Entity"
HTTP status code 422, known as "Unprocessable Entity", is typically used in the context of web APIs to indicate that the server understands the request but cannot process it due to semantic errors. It signifies that the request was well-formed, but the server was unable to perform the requested action because of validation errors or business logic constraints. This status code is commonly employed when input data fails validation checks, such as missing required fields, invalid data formats, or out-of-range values. It helps to distinguish between syntactically correct requests and those with semantic issues, enabling clients to understand and address the errors accordingly.
FastAPI and HTTP status code 422
FastAPI returns HTTP status code 422 when a validation fails. In the example below, a query parameter was missing in the request.
# HTTP status code 500: "Internal Server Error"
The HTTP 500 "Internal Server Error" server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
This error response is a generic "catch-all" response. Usually, this indicates the server cannot find a better 5xx error code to response. Sometimes, server administrators log error responses like the 500 status code with more details about the request to prevent the error from happening again in the future.
When running an API with FastAPI, encountering status code 500 usually indicates that there is a problem in program code, for example an unexpected error thrown by Python.
Want to know more?
Do you want to get to know all existing HTTP status codes in a fun way? Have a look at the overview of all existing HTTP status codes on the website of HTTP Cats (opens new window). And if you want to go straight to the interesting ones: status code 418 might be an excellent one to start with.