Understanding API Requests and Responses

Learn how API requests and responses work, including HTTP methods, status codes, headers, and body formats. A complete guide for technical writers and developers to understand the core of API communication.

So, you’ve met the data types—Boolean, Strings, Numbers, and their pals. Now, let’s see them in action! APIs are all about communication: You send a request, and you get a response. Think of it like texting a friend—you ask a question (request), and they reply (response). Simple, right?

Well, APIs work in the same way but with a bit more structure. Let’s break it down!

Note

If you're feeling a bit lost with all the technical jargon, don't worry! This chapter will guide you through API requests and responses step by step. By the end, you'll be making API calls like a pro!

What is an API Request?

Imagine you’re at a restaurant. You tell the waiter, “I’d like a margherita pizza, please!” That’s a request. The waiter (the API) takes your order, processes it, and brings back a pizza (the response).

An API request has a few main ingredients:

The Endpoint (URL): This is where the request goes, like in REST APIs.
The HTTP Method: Think of it as the type of request you’re making (like asking for a menu vs. placing an order).
Headers: Extra info you send along with your request (like saying “No olives, please”).
Query Parameters: These refine your request (like asking for extra cheese).
Request Body (for some requests): If you’re sending data (like placing an order), it goes here.

Example: Making a GET Request to an API Endpoint

Let’s say we want to find a book by its title.

   GET https://api.example.com/books?title=harry%20potter

The endpoint is https://api.example.com/books
The method is GET (because we just want to retrieve data)
The query parameter is title=harry%20potter (we’re looking for books titled Harry Potter)

What is an API Response?

Great, you placed your order. Now the waiter brings back your pizza (hopefully the right one!).

An API response usually includes:

The Status Code: A quick signal of whether the request was successful.
Headers: More details about the response.
The Body: The actual data you asked for (your pizza!).

Example: A JSON Response from an API

Here’s what the API might return for our Harry Potter book request:

{
  "title": "Harry Potter and the Sorcerer's Stone",
  "author": "J.K. Rowling",
  "published_year": 1997,
  "genre": "Fantasy"
}

This is structured as JSON, one of the most common data formats used in modern APIs.

HTTP Methods: The Different Types of API Requests

APIs aren’t just about getting data; they can also send, update, and delete information. That’s where HTTP methods come in.

HTTP Method	Purpose	Common Use Cases	Request Body?	Safe?	Idempotent?
GET	Retrieves data from the server	Fetching resource details Search operations Listing collections	No	Yes	Yes
POST	Creates new data on the server	Creating new resources Submitting forms Complex operations	Yes	No	No
PUT	Updates existing data (complete replacement)	Updating all fields of a resource Replacing existing resources	Yes	No	Yes
PATCH	Partially updates existing data	Updating specific fields Partial modifications	Yes	No	Sometimes
DELETE	Removes data from the server	Deleting resources Removing records	Sometimes	No	Yes

Important

In RESTful APIs, HTTP methods are mapped to CRUD operations: GET (Read), POST (Create), PUT/PATCH (Update), and DELETE (Delete). The 'Safe' property means the method doesn't change server state, while 'Idempotent' means multiple identical requests have the same effect as a single request.

Example: A POST Request for Creating Resources

POST https://api.example.com/books Content-Type: application/json

{
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "published_year": 1937
}

This tells the API: “Hey, add this book to the database!” The Content-Type header specifies we’re sending JSON data.

Understanding API Status Codes

When you get a text reply, sometimes it’s all good, sometimes it’s confusing, and sometimes it’s just… an error. APIs use status codes to tell you how things went.

Code Range	Category	Common Codes	Description	Developer Action
2xx	Success	200 OK	The request was successful	Process the returned data
		201 Created	New resource created successfully	Use the returned resource ID for further operations
		204 No Content	Request succeeded, but no content returned	Continue with application flow, no data to process
3xx	Redirection	301 Moved Permanently	Resource has moved to a new URL	Update bookmarks and links
		304 Not Modified	Resource hasn't changed since last request	Use cached version of the resource
4xx	Client Error	400 Bad Request	Invalid syntax in the request	Check request format and parameters
		401 Unauthorized	Authentication required	Provide authentication credentials
		403 Forbidden	Client doesn't have access rights	Request access or use different credentials
		404 Not Found	Resource doesn't exist	Check the URL and resource ID
		429 Too Many Requests	Client sent too many requests	Implement rate limiting or backoff strategy
5xx	Server Error	500 Internal Server Error	Server encountered an error	Report the issue to API provider
		503 Service Unavailable	Server temporarily unavailable	Retry the request after a delay

API Authentication and Security

Many APIs require authentication to ensure only authorized users can access certain resources. Common authentication methods include:

Authentication Method	Implementation	Ideal For	Security Level	Advantages	Disadvantages
API Keys	Single token sent in header, query param, or cookie	Public APIs with moderate security needs	Basic	Simple to implement Low developer friction	Can be intercepted Limited granular control
Basic Auth	Base64 encoded username:password in header	Internal APIs, development environments	Low	Universal support Simple to implement	Credentials sent with every request Base64 is easily decoded
OAuth 2.0	Token-based authorization framework	APIs accessing user data across services	High	Granular access control Token expiration Doesn't expose credentials	Complex implementation Higher developer overhead
JWT	Signed tokens with encoded claims	Modern web applications, microservices	High	Self-contained Stateless authentication Can contain user data	Can't be revoked before expiration Size increases with claims

How to Test API Requests

Now that you understand API requests and responses, how do you test them? These tools will help you explore and validate APIs:

Tool	Category	Key Features	Best For	Complexity	Price
Postman	GUI Application	Request collections Environment variables Automated testing Team collaboration	API development Comprehensive testing Team workflows	Medium	Free tier + Paid plans
> cURL	Command Line	Universal availability Scriptable Detailed control SSL support	CI/CD integration Shell scripting Quick testing	Medium-High	Free Open Source
Swagger UI	Interactive Docs	OpenAPI integration Try-it-out feature Self-documenting Code generation	API exploration Developer portals Documentation	Low	Free Open Source
Insomnia	GUI Application	Clean interface GraphQL support Plugin system Design spec	GraphQL APIs Individual developers Design-first approach	Low	Free tier + Paid plans

Common API Documentation Components

When documenting APIs, it’s important to include:

Endpoint details: Base URL and path
HTTP method: GET, POST, PUT, DELETE, etc.
Request parameters: Query parameters, path parameters
Request headers: Content-Type, Authorization, etc.
Request body schema: For POST/PUT requests
Response structure: What the API returns
Status codes: Possible response codes and their meanings
Examples: Sample requests and responses

Key Takeaways

API requests contain an endpoint, HTTP method, headers, and sometimes a body
API responses include status codes, headers, and response data
Common HTTP methods are GET (retrieve), POST (create), PUT (update), DELETE (remove)
Status codes indicate success (2xx), client errors (4xx), or server errors (5xx)
Authentication methods secure APIs against unauthorized access
Tools like Postman, cURL, and Swagger help test and explore APIs
Comprehensive API documentation includes endpoints, parameters, examples, and response schemas

Wrapping it up!

Congrats! You now understand how API requests and responses work. Whether it’s fetching data, sending new information, or handling errors, you’ve got the basics down.

Now that you know how APIs send and receive data, it’s time to document them effectively! In the next chapter, we’ll dive into how to write clear and structured API documentation that developers will love. Get ready to level up your documentation skills!

API Communication Resources

Expand your understanding of API requests and responses with these resources.

External Resources

Tools & APIs

Start your learning journey!

Course Progress 0%

0 of 0 pages completed

Found value in the course?

Your support fuels my work!

Have an issue?

Help improve the course by reporting an issue