After learning about method & path, the next step in reading and using APIs is understanding parameters. Parameters allow you to customize requests, filter results, and provide input to the API.We’ll continue using the Petstore API to illustrate different types of parameters.
1. What Are Parameters?#
Parameters are pieces of information sent to the API to tell it what exactly you want. They can appear in different places in the request:| Type | Where it Appears | Example Purpose |
|---|
| Path Parameters | Part of the URL path, often in {} | /pets/{id} specifies which pet to fetch |
| Query Parameters | After ? in the URL | /pets?status=AVAILABLE filters pets by status |
| Header Parameters | In HTTP headers | Authorization: Bearer <token> for authentication |
| Body Parameters | In request body (for POST/PUT/PATCH) | JSON object with pet details |
2. Path Parameters#
Path parameters are required values embedded in the URL path. They identify a specific resource.{id} is the path parameter. Replace it with a real pet ID:
GET https://api.petstoreapi.com/v1/pets/pet_1Nv0FGQ9RKHgCVdK
pet_1Nv0FGQ9RKHgCVdK.
3. Query Parameters#
Query parameters are optional (sometimes required) values added after ? in the URL. Multiple query parameters are separated by &.GET /pets?status=AVAILABLE
status=AVAILABLE is the query parameter.
You could add multiple parameters:
/pets?status=AVAILABLE&species=DOG
Filtering results (status, category)
Pagination (limit, offset)
Header parameters are sent inside the HTTP headers instead of the URL. They often carry:Authentication tokens (Authorization)
Content type (Content-Type: application/json)
Custom metadata (X-Request-ID)
GET /pets/pet_1Nv0FGQ9RKHgCVdK
Headers:
Authorization: Bearer <your-token>
Accept: application/json
Most headers are automatically handled by tools or frameworks, so you usually don’t need to set them manually; however, authentication-related headers (like Authorization) often need to be added yourself.
5. Body Parameters#
Body parameters are used for methods that create or update data (POST, PUT, PATCH). They are usually in JSON format, but could also be form data or XML.POST /pets
Body (JSON):
{
"name": "Fluffy",
"species": "DOG",
"breed": "Golden Retriever",
"ageMonths": 24,
"status": "AVAILABLE"
}
The body contains structured data for the new resource.
The API spec defines which fields are required and their types.
The body is usually the most complex part of a request, since it often requires a specific and sometimes nested structure. You need to carefully follow the API documentation to construct it correctly.Fortunately, tools like Apidog can help you easily build a properly formatted body that meets the API’s requirements.
6. Practical Tips#
1.
Always check which parameters are required in the spec. Missing required parameters usually trigger a 400 Bad Request.
2.
Optional parameters can enhance your request (filter, sort, paginate).
3.
Use URL encoding for query parameters that contain spaces or special characters.
4.
Tools like Apidog or Postman make it easier to add parameters in the right place and see the request URL generated.
5.
Remember: path parameters are required, query parameters are usually optional, and body parameters depend on the HTTP method.
7. Key Takeaways#
Parameters define what data you are asking for or what data you are sending.
Path parameters identify specific resources.
Query parameters filter, sort, and paginate results.
Header parameters pass metadata or authentication.
Body parameters carry structured data for POST/PUT/PATCH requests.
Reading the API spec carefully ensures you pass parameters correctly and get the expected response.
Now that you have a solid understanding of the different types of parameters and how to use them, you’re ready to take the next step. In the following section, we’ll dive deeper into the Request Body—exploring how to structure data for complex API operations and best practices for building valid and effective request payloads. 