Apidog

All-in-one Collaborative API Development Platform

API Design

API Documentation

API Debugging

API Mock

API Automated Testing

Sign up for free

The Essential Guide to HTTP Request Parameters in REST API

Start for free
Contents
Home / Basic Knowledge / The Essential Guide to HTTP Request Parameters in REST API

The Essential Guide to HTTP Request Parameters in REST API

Request parameters allow you to pass data to an API endpoint when making a request. They are an important part of designing and using REST APIs.

Request parameters allow you to pass data to an API endpoint when making a request. They are an important part of designing and using REST APIs. In this guide, we'll cover everything you need to know about request parameters, including how to use them with different HTTP methods like GET, POST, PUT and DELETE in Apidog.

button

What are Request Parameters in API?

Request parameters, also known as query parameters or URL parameters, are key-value pairs that are appended to the URL when making an API request. They allow the client to pass data to the API in a simple and standardized way.

Some examples of request parameters:

/users?id=1234
/posts?category=tech&sort=asc
/search?q=hello+world

The parameters come after the ? in the URL, separated by an &. The server can then access these parameters to handle the request accordingly.

Why Use Request Parameters?

Here are some of the main benefits of using REST API parameters:

  • Simplicity - Appending key-value pairs to the URL is an easy way to pass data. The client doesn't need to construct a complex request body.
  • Flexibility - Parameters can be combined in different ways to support various use cases. New parameters can easily be introduced without breaking existing clients.
  • Caching - URLs with different parameters can be cached separately by browsers and CDNs.
  • Bookmarks - URLs with parameters can be bookmarked for later use.
  • Logging - Parameter values appear directly in server access logs for tracking and analytics.
  • Encoding - URLs easily support encoding of parameter values, such as spaces to %20.

Overall, request parameters provide a simple, flexible way to pass data to APIs that fit nicely into the REST architectural style.

Request Params Types

There are two main types of request params:

Query Parameters

Query parameters are the most common type. They are appended to the URL path after a ? character:

/users?page=1&per_page=20

Query params work well for filtering, sorting, pagination, and simple lookups.

Path Parameters

Path parameters are Baked into the URL path itself:

/users/{userId}

This allows identifiers and fixed attributes to appear directly in the resource path for more RESTful, self-documenting APIs. Path params are also required for many URI patterns like collection/element.

Most modern API frameworks like Express support both query and path parameters.

Using Parameters with HTTP Methods

Request parameters can be used with any HTTP method like GET, POST, PUT and DELETE. However, there are best practices around which to use in different situations.

GET Requests

GET requests should use query parameters exclusively. Path parameters can also work for simple lookups by ID.

GET requests with query params are safe, cacheable, and easy to construct. This makes them ideal for:

  • Filtering results
  • Pagination
  • Sorting
  • Partial response

For example:

GET /users?status=active&sort=-createdAt
5 Ways to Make HTTP GET Requests
This post explores the essentials of GET requests in web development. By focusing on the core concept of sending GET requests, developers can gain a clearer understanding of this fundamental aspect of HTTP.

POST Requests

POST requests support both query and path parameters.

However, it's best practice to avoid query parameters for POSTs in REST APIs. This keeps the request data together in the body and avoids potential issues with parameter encoding and caching.

Instead, use path parameters to identify resources and put the remaining data in the request body as JSON:

POST /users/{userId}/comments
{
  "text": "Hello World!" 
}
How to Send an HTTP POST Requests with cURL/Axios/Postman
This article delves into the essentials of sending POST requests, exploring the methods of sending HTTP POST requests using different tools—Apidog, cURL, Axios, and Postman. This will help you gain a better understanding and implementation of this essential development task.

PUT Requests

Like POST, PUT requests should avoid query parameters and use path parameters to identify the resource being updated. The update data itself should go in the request body:

PUT /users/{userId}
{
  "firstName": "Jane"
}

DELETE Requests

DELETE requests should use path parameters to identify the resource being deleted:

DELETE /users/{userId}

Query parameters are not commonly used with DELETE.

Request Parameters in Apidog

Apidog is an API documentation tool that allows you to generate documentation for your APIs based on request parameters and other relevant information. To introduce Apidog using request parameters, you can follow these ways:

Request Parameter Documentation: In Apidog, you can document request parameters by specifying their names, types, descriptions, and any validation rules or constraints. This ensures that developers using your API understand what data is expected in each request.

Endpoint Description: You can associate request parameters with specific API endpoints. For each endpoint, you can describe its purpose and functionality, making it clear how the request parameters fit into the overall API workflow.

Example Requests: Apidog allows you to include sample request examples that demonstrate how to send parameters in a request. These examples can include the HTTP method (e.g., GET, POST), endpoint URL, and the request body or query parameters.

button

Best Practices

Here are some key best practices around working with request parameters in REST APIs:

  • Use descriptive, lowercase parameter names like user_id instead of id.
  • Avoid redundant params - the URI itself should be descriptive enough.
  • Document your parameters - Don't force users to guess!
  • Keep parameter names consistent across your APIs.
  • Use camelCase for parameter names in JSON, snake_case in URLs.
  • Avoid large parameter values - Prefer IDs and references over huge strings.
  • Use proper encoding for parameter values, like encoding spaces as %20.

Sticking to these best practices will ensure your parameters are clean, consistent, and easy for developers to work with.

Accessing Parameters in Code

On the server side, access and validate parameter values from the request before using them.

In Express, parameters are available in the req.params and req.query objects:

app.get('/users', (req, res) => {
  const sort = req.query.sort;
  const limit = req.query.limit;
  
  // ...
})

Frameworks like Express will decode parameter values from the URL encoding for you.

On the client side, there are libraries like qs that help generate and parse parameter strings.

Parameter Validation

It's important to validate parameters coming from clients to avoid security issues and bad data:

  • Type Check - Make sure the parameter is the expected type like number, string, etc.
  • Value Check - Validate against an allowable set of values, range, regex pattern, etc.
  • Required - Ensure required parameters are present.
  • Sanitize - Trim, escape, encode, etc. to prevent XSS and other injection attacks.

Doing proper parameter validation is critical for secure, production-ready APIs. Frameworks like Express Validator make validation much easier.

In Summary

Request parameters allow passing simple data to APIs in a standardized way that fits REST principles.

Follow these best practices when using request parameters:

  • Stick to query params for GET, path params for POST/PUT/DELETE.
  • Avoid query params in request bodies - put data in body instead.
  • Validate, sanitize, and document parameters properly.
  • Keep parameters consistent across APIs.
button