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. 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.

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:

Copy code
/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 request parameters in REST APIs:

• 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.

Parameter Types

There are two main types of request parameters:

Query Parameters

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

Copy code
/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:

Copy code
/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:

Copy code
GET /users?status=active&sort=-createdAt

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:

Copy code
POST /users/{userId}/comments
{
  "text": "Hello World!" 
}

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:

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

DELETE Requests

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

Copy code
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 provide a description of 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.

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:

js
Copy code
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.