Path Parameters

Introduction

Most REST APIs work with individual resources such as a specific user, product, order, employee, account, invoice, payment, ticket, or customer. When a client wants to retrieve, update, replace, or delete one exact resource, the API needs a clean way to identify that resource in the request. Path parameters solve this problem by placing dynamic values directly inside the URL path.

For example, an application may store thousands or millions of users. Creating separate endpoints such as /users/user101, /users/user102, and /users/user103 would be impossible to maintain. Instead, REST APIs use an endpoint template such as /users/{id}. When the client requests /users/101, the value 101 is the path parameter that identifies the user.

Path parameters are one of the most common concepts in REST API design and testing. They appear in simple CRUD APIs, enterprise APIs, microservices, public APIs, and internal service calls. They are also a frequent source of defects because they deal with identity, validation, authorization, routing, and security. A valid ID should return the correct resource. An invalid ID should fail safely. An unauthorized ID should not expose someone else's data.

For API testers, path parameter testing is not just about replacing {id} with a number. A complete testing approach covers valid values, invalid values, missing values, malformed values, boundary values, special characters, URL encoding, authorization checks, injection attempts, and response status codes. Understanding path parameters helps testers design stronger API coverage and explain REST endpoint behavior clearly in interviews.

What Are Path Parameters?

A path parameter is a variable value embedded within the URL path that identifies a specific resource or narrows the route to a specific resource relationship. It is part of the endpoint path itself, not an optional filter placed after a question mark. In /users/101, the value 101 is a path parameter. In /orders/7001, the value 7001 is a path parameter.

Endpoint documentation often shows path parameters using curly braces. For example, /users/{id} means the API expects a dynamic value in the location represented by {id}. The actual request replaces that placeholder with a real value, such as /users/101. Tools such as OpenAPI, Postman, REST Assured, and Karate all support this concept.

Path parameters are normally required because they are part of the route. If a client requests /users/{id}, it must provide an ID value to identify the user. Without the value, the request may become a different endpoint, such as /users, which might represent the user collection instead of one user. This is why missing path parameter behavior must be tested carefully.

A simple definition is this: a path parameter is a dynamic value in the URL path used to identify a specific API resource.

Basic Syntax

The general syntax for a path parameter is /resource/{parameter}. The resource name identifies the collection or parent resource. The parameter placeholder identifies the dynamic value that will be supplied at runtime. For example, /users/{id} is a template, while /users/101 is an actual request path.

In many APIs, parameter names are more specific than simply {id}. A user endpoint may use {userId}. An order endpoint may use {orderId}. A product endpoint may use {productId}. Meaningful names improve documentation and reduce confusion when multiple parameters appear in one path.

Endpoint template:
/users/{id}

Actual request:
GET /users/101

In this example, /users is the resource collection and 101 is the path parameter. The GET method tells the server to retrieve the resource. The path parameter tells the server which user should be retrieved.

Why Path Parameters Are Needed

Path parameters make APIs reusable and scalable. Without them, every resource would require its own hardcoded endpoint. That approach does not work in real applications because resources are created and deleted dynamically. New users, orders, accounts, and products appear all the time. The API cannot create a new static route for each item.

With path parameters, the route pattern stays stable while the value changes. /users/101, /users/102, and /users/103 all use the same endpoint template: /users/{id}. The server extracts the path value and uses it to locate the requested resource. This keeps API design clean and avoids endpoint explosion.

Path parameters also make APIs easier to understand. When a tester sees GET /products/500, it is clear that the request is about product 500. When a tester sees DELETE /orders/7001, it is clear that the request deletes or cancels order 7001 depending on the API contract. The resource identity is visible in the URL path.

They are also essential for automation. Automated tests can create a resource, capture its ID from the response, and use that ID as a path parameter in later requests. This allows tests to work with fresh data instead of relying on fixed records that may change or disappear.

Path Parameter Structure

Consider the URL https://api.example.com/v1/users/101. The protocol is https. The host is api.example.com. The API version is /v1. The resource collection is /users. The path parameter is 101. Each part has a different responsibility.

Path parameters are part of routing. The server framework usually matches the request path against a route template. If the route template is /users/{id}, the framework extracts the value after /users/ and passes it to the handler method. The application then validates the value, checks permissions, fetches the resource, and returns a response.

Common Examples

Path parameters appear in many everyday API requests. GET /users/101 retrieves user 101. GET /products/500 retrieves product 500. GET /orders/7001 retrieves order 7001. GET /employees/45 retrieves employee 45. GET /customers/900 retrieves customer 900.

They are also used for update and delete operations. PUT /users/101 may replace user 101. PATCH /products/500 may update selected fields for product 500. DELETE /orders/7001 may remove or cancel order 7001. The path parameter identifies the target of the operation.

Real APIs may use numeric IDs, UUIDs, slugs, codes, names, or composite values as path parameters. A product may be identified by /products/500 or by /products/wireless-keyboard. A repository may be identified by /repos/openai/chatgpt. A bank account may be identified by an account number or opaque account ID. The format depends on the API contract.

Multiple Path Parameters

Some endpoints require more than one path parameter. For example, /departments/{departmentId}/employees/{employeeId} contains two dynamic values. A real request may be GET /departments/20/employees/101. Here, 20 identifies the department and 101 identifies the employee within that department context.

Another example is /customers/{customerId}/orders/{orderId}. A request such as GET /customers/500/orders/1001 identifies customer 500 and order 1001. The API should verify that order 1001 belongs to customer 500. If the order exists but belongs to another customer, the response should not expose it under the wrong parent.

Multiple path parameters increase testing responsibility. Testers must check valid combinations, invalid parent IDs, invalid child IDs, mismatched parent-child combinations, unauthorized parent resources, unauthorized child resources, and malformed values. A route can be syntactically valid but still semantically wrong if the relationship between values is invalid.

Meaningful parameter names matter even more when multiple values are used. /departments/{departmentId}/employees/{employeeId} is clearer than /departments/{id}/employees/{id}. Clear names improve documentation and help automation code pass the correct values.

Path Parameters in CRUD Operations

Path parameters are heavily used in CRUD operations. CRUD stands for Create, Read, Update, and Delete. Create operations often use the collection endpoint, such as POST /users, because the resource does not have an ID until it is created. Read, update, and delete operations commonly use path parameters because they operate on one existing resource.

For reading, GET /users/101 retrieves user 101. For replacing, PUT /users/101 replaces the full representation of user 101. For partial update, PATCH /users/101 updates selected fields. For deletion, DELETE /users/101 deletes, deactivates, or removes user 101 according to the API design.

In automation, a common pattern is create-read-update-delete. The test sends POST /users, captures the generated user ID, calls GET /users/{id} to verify creation, calls PATCH /users/{id} or PUT /users/{id} to update it, and finally calls DELETE /users/{id} to clean up. The path parameter connects the steps using the actual resource created during the test.

This pattern reduces dependency on static test data. Instead of assuming user 101 always exists, the test creates a user and uses its returned ID. That makes tests more independent, repeatable, and safe for parallel execution when cleanup is handled correctly.

Path Parameters vs Query Parameters

Path parameters and query parameters are often confused. A path parameter identifies a specific resource. A query parameter filters, sorts, searches, paginates, or modifies the result. In /users/101, 101 identifies one user. In /users?city=Chicago, city=Chicago filters the user collection.

A useful rule is this: if the value is needed to locate the resource, use a path parameter. If the value changes how a collection is filtered or displayed, use a query parameter. /orders/7001 identifies one order. /orders?status=pending filters many orders.

REST Assured Example

REST Assured supports path parameters through the pathParam method. This keeps endpoint templates readable and avoids manual string concatenation. For example:

given()
  .pathParam("id", 101)
  .when()
  .get("/users/{id}")
  .then()
  .statusCode(200);

The actual request becomes GET /users/101. The placeholder {id} is replaced by the value passed through pathParam. This approach is cleaner than building the URL manually with string concatenation, especially when values come from earlier API responses.

REST Assured also supports multiple path parameters. A test can pass departmentId and employeeId separately and call /departments/{departmentId}/employees/{employeeId}. This makes parameter usage explicit and reduces the chance of placing values in the wrong order.

In a mature framework, path parameter values often come from test data builders, response extraction, database setup, or scenario context. The key is to keep the route template stable and inject the values safely.

Postman Example

In Postman, path parameters are often represented through variables. A request may use {{baseUrl}}/users/{{userId}}, where baseUrl is the environment URL and userId is a variable containing the ID value. If userId is 101, the request becomes GET /users/101.

Postman variables can come from environments, collections, globals, data files, or scripts. For example, a create user request can store the returned ID into a variable, and the next request can use that variable as a path parameter. This supports chained workflows such as create user, retrieve user, update user, and delete user.

Testers should name variables clearly. userId, orderId, productId, and customerId are better than generic names such as id1 or value. Clear variable names reduce mistakes when collections grow.

Karate Example

Karate provides a clean way to build paths using the path keyword. A simple request may look like this:

Given path 'users', 101
When method GET
Then status 200

The actual request becomes GET /users/101. Karate joins the path segments correctly, so testers do not need to manually manage slashes. This is useful because URL construction mistakes are common in API automation.

For multiple path parameters, Karate can combine several path segments. For example, Given path 'departments', 20, 'employees', 101 builds /departments/20/employees/101. This keeps test scenarios readable while still allowing dynamic values.

Path Parameters in API Testing

Path parameter testing should start with valid values. If GET /users/101 is called with an existing user ID and valid authorization, the API should return 200 OK and the response should describe user 101. The returned ID should match the requested ID. The response should not accidentally return another user's data.

Invalid values are equally important. If the client calls GET /users/999999 and that user does not exist, the API should return an appropriate response such as 404 Not Found. If the API uses a different documented behavior, the test should follow the contract. The key is that nonexistent resources should not return misleading success responses.

Missing path parameters should be tested carefully. GET /users/ may call the collection endpoint /users depending on routing. If the test intends to call an individual user endpoint, the missing ID may result in different behavior. The API should distinguish collection endpoints and individual resource endpoints clearly.

Malformed values should also be tested. If user IDs are numeric, GET /users/ABC should not cause an unhandled server error. Depending on the design, it may return 400 Bad Request for invalid format or 404 Not Found if no matching route exists. Negative numbers, zero, extremely large numbers, spaces, reserved characters, encoded characters, and injection-like strings should all be considered.

Authorization Testing with Path Parameters

Path parameters are closely tied to authorization because they expose resource identity in the URL. If a user can change /accounts/1001 to /accounts/1002 and see another user's account, the API has an object-level authorization defect. This is one of the most important security risks in API testing.

Authorization tests should include users with different roles, tenants, organizations, ownership boundaries, and permissions. A regular user should access only their allowed resources. An admin may access broader resources depending on policy. A user from one tenant should not access resources from another tenant by changing a path parameter.

Tests should also verify update and delete operations. It is not enough to protect GET. If a user cannot read another user's order but can update or delete it through a path parameter, the API is still vulnerable. Every method using the path parameter must enforce authorization.

Good defect reports for path authorization issues should include the user role, requested endpoint, path parameter value, expected access rule, actual response, and evidence that the resource belongs to another user or tenant. Clear reporting helps developers fix the rule correctly.

Security Testing with Path Parameters

Path parameters must be validated safely. Attackers may pass unexpected values such as SQL fragments, script-like strings, encoded slashes, path traversal patterns, very long values, or special characters. The API should reject invalid input safely and should not expose stack traces, SQL errors, internal class names, or database details.

An example injection-style request may be /users/101%20OR%201=1. The API should not treat this as a valid database condition. It should validate the parameter format before using it in queries. If numeric IDs are expected, only numeric values within allowed bounds should be accepted.

Encoded characters need attention. Some identifiers may legitimately contain slashes, spaces, or special characters if they are slugs or names. In that case, URL encoding rules must be documented and tested. If slashes are not allowed inside the value, encoded slash behavior should be controlled so routing cannot be bypassed.

Security-focused tests should check that invalid values produce controlled client errors, not server crashes. They should also confirm that logs do not expose sensitive path parameter values unnecessarily, especially when IDs represent accounts, records, or personal information.

Designing Path Parameters Well

Good path parameter design starts with clarity. The parameter should represent the resource identity at that point in the path. If the endpoint is /users/{userId}, the value should identify a user. If the endpoint is /orders/{orderId}, the value should identify an order. Avoid using path parameters for vague values that do not clearly belong to the resource hierarchy.

Parameter names should describe the domain concept. A path such as /customers/{customerId}/orders/{orderId} is easier to understand than /customers/{id1}/orders/{id2}. Meaningful names also help generated documentation, OpenAPI specifications, test reports, and automation helper methods. When tests fail, a report that says customerId is invalid is more useful than a report that says id is invalid.

Teams should also decide whether identifiers are sequential numbers, UUIDs, slugs, or opaque strings. Sequential numeric IDs are simple, but they may be easy to enumerate. UUIDs are harder to guess but longer to read. Slugs are human-readable but require careful validation and encoding. Opaque IDs hide implementation details but may require good tooling for debugging. The API contract should make the chosen format explicit.

Path parameters should remain stable. If a resource is exposed as /users/{userId}, changing that identifier format later can break clients. If the internal database key changes, the API should ideally preserve the public identifier or introduce a controlled migration path. The URL is part of the API contract, and path parameter decisions should be treated with the same seriousness as request and response fields.

Automation Data Flow with Path Parameters

In automated API testing, path parameters are often produced dynamically. A test may create a customer, extract the returned customer ID, and use that value in later requests. This data flow is healthier than relying on permanent shared records because it gives the test control over its setup and cleanup. It also reduces failures caused by stale or modified test data.

A common flow starts with POST /users. The response returns an ID. The test stores that ID in memory, then calls GET /users/{userId} to verify the created resource. Next, it may call PATCH /users/{userId} to update the same record and finally DELETE /users/{userId} to clean it up. Each request depends on the same path parameter value captured from the create response.

Parallel execution makes this pattern even more important. If multiple tests use the same hardcoded ID, they can interfere with each other. One test may delete a record while another test is trying to read it. Dynamic IDs avoid this problem because each test owns its own resource. When tests create their own data, path parameters become part of the test's private context.

Automation should also handle cleanup failures thoughtfully. If a test creates a resource and later fails before deletion, a cleanup hook or teardown process should still try to remove the resource using the captured path parameter. Good reporting should include the generated ID so developers and testers can inspect the leftover data if cleanup fails.

Path Parameter Validation Checklist

A practical validation checklist includes valid ID, invalid ID, missing ID, maximum value, minimum value, negative value, zero value, non-numeric value, special characters, URL encoding, unauthorized access, forbidden access, deleted resource access, and performance with large or unusual values. Not every endpoint needs every test in every suite, but high-risk endpoints should receive broad coverage.

Boundary values are useful when IDs are numeric. Test zero, one, negative one, very large numbers, and values outside the supported range. If the API uses UUIDs, test valid UUIDs, malformed UUIDs, empty strings, uppercase and lowercase forms if relevant, and nonexistent UUIDs. If the API uses slugs, test spaces, hyphens, underscores, case sensitivity, and encoded characters.

Relationship checks are important for nested endpoints. If an endpoint contains both customer ID and order ID, verify that the order belongs to the customer. If it does not, the API should not return unrelated data. This prevents relationship-bypass defects.

Performance checks may matter for path parameters that trigger database lookups. Extremely large IDs or malformed values should not cause slow queries. The API should validate early and fail fast where possible.

Common Mistakes

A common mistake is using query parameters for resource identity, such as /users?id=101, when the API is retrieving one specific user. While this can work technically, /users/101 is clearer for REST resource design. Query parameters are better suited for filtering collections, such as /users?city=Chicago.

Another mistake is using verbs in the path, such as /getUser/101. In REST, the URI should identify the resource and the HTTP method should identify the action. GET /users/101 is cleaner than GET /getUser/101.

Inconsistent parameter naming is also common. One endpoint may use {id}, another {userId}, another {userNumber}, and another {uid} for the same concept. Consistent names make documentation and automation easier. If values represent different concepts, names should make that distinction clear.

Not validating IDs is a serious mistake. APIs should not assume path parameters are always valid just because the route matched. Validation, authorization, and safe error handling are required for every path value that reaches business logic.

Best Practices

Use path parameters only when identifying a specific resource or a required parent-child relationship. Keep parameter names meaningful, such as {userId}, {orderId}, {productId}, or {customerId}. Avoid vague names when multiple parameters exist in one path.

Validate all path parameter values. Numeric IDs should be checked for numeric format and allowed range. UUIDs should be checked for valid UUID format. Slugs should be checked for allowed characters. Invalid values should return clear client errors or documented not-found responses, never unhandled server errors.

Return appropriate status codes. A nonexistent resource commonly returns 404 Not Found. An invalid parameter format may return 400 Bad Request. Unauthorized requests should return 401 when authentication is missing or invalid. Forbidden requests should return 403 when the caller is authenticated but not allowed. The exact behavior should be documented and consistent.

Document all path parameters in the API specification. Documentation should include parameter name, location, type, required status, example value, validation rules, and expected error responses. OpenAPI documentation is especially helpful because it allows tools and tests to understand path parameters structurally.

Avoid exposing sensitive internal identifiers unless intended. Sometimes APIs use opaque IDs or UUIDs instead of sequential database IDs to reduce enumeration risk. This does not replace authorization, but it can reduce information leakage. The server must still verify access for every requested resource.

Real-World Scenario

Suppose an e-commerce API exposes product operations. GET /products/500 retrieves product 500. PUT /products/500 replaces product 500. PATCH /products/500 updates selected fields. DELETE /products/500 deletes or deactivates product 500. In every case, 500 is the path parameter identifying the product.

A strong test suite would first create or identify a valid product. It would verify that retrieving the product returns the same product ID. It would update the product and verify the change applies only to that product. It would test invalid product IDs, deleted product IDs, non-numeric values if IDs are numeric, and unauthorized access by users who are not allowed to modify products.

If the product belongs to a seller, a nested endpoint such as /sellers/20/products/500 must also verify the relationship. Product 500 should belong to seller 20. If it belongs to seller 30, the API should not return it under seller 20. This kind of relationship validation catches defects that simple happy-path tests miss.

Interview Questions

A common interview question is: what is a path parameter? A strong answer is that a path parameter is a dynamic value embedded in the URL path to identify a specific resource. In GET /users/101, 101 is the path parameter identifying the user.

Another common question is when path parameters should be used. They should be used when accessing, updating, replacing, or deleting a specific resource. They are also used when a route needs a required parent-child relationship, such as customer ID and order ID.

Interviewers may ask the difference between path parameters and query parameters. Path parameters identify specific resources and are part of the URL path. Query parameters appear after the question mark and are generally used for filtering, sorting, searching, pagination, or optional behavior.

A testing-focused answer should mention positive, negative, boundary, authorization, and security testing. It should also mention that changing path parameter values must not allow users to access resources they do not own.

Interview-Ready Explanation

Path parameters are dynamic values embedded within the URL path that uniquely identify a specific resource in a REST API. They are part of the endpoint itself and are commonly used for operations such as retrieving, updating, replacing, or deleting one resource. For example, in GET /users/101, the value 101 is the path parameter identifying the user.

Path parameters differ from query parameters because path parameters identify resources, while query parameters usually filter, sort, search, or paginate collections. /users/101 points to one specific user. /users?city=Chicago points to the users collection filtered by city.

In API testing, path parameters should be validated with valid IDs, invalid IDs, missing values, malformed values, boundary values, special characters, URL encoding, unauthorized access, forbidden access, and security attack patterns. Tests should verify correct status codes, safe error responses, resource ownership, and relationship rules in nested endpoints. Strong path parameter testing helps prevent functional defects and serious authorization issues.

Key Takeaway

Path parameters are the dynamic parts of an API URL that identify specific resources. They make REST endpoints reusable, scalable, and readable. Instead of creating a separate endpoint for every user, product, or order, the API defines a route template such as /users/{userId} and accepts different values at runtime.

The practical rule is simple: use path parameters for resource identity and query parameters for filtering or optional request behavior. Validate every path parameter, document it clearly, and test it across positive, negative, boundary, authorization, and security scenarios. Because path parameters often point directly to business records, they deserve careful attention in every serious API testing strategy.