Path Parameters

Last Updated Aug 05, 2021

What are Path Parameters?

Path parameters are request parameters attached to a URL that point to a specific REST API resource. The path parameter is separated from the URL by a `/`, and from the query parameter(s) by a question mark (`?`). The path parameter defines the resource location, while the query parameter defines sort, pagination, or filter operations. The user's input (the query) is passed as a variable in the query parameter, while each path parameter must be substituted with an actual value when the client makes an API call. The path parameter is contained within curly braces.

Path Parameter Example

Path parameters are part of the endpoint and are required. For example, `/users/{id}`, `{id}` is the path parameter of the endpoint `/users`- it is pointing to a specific user's record. An endpoint can have multiple path parameters, like in the example `/organizations/{orgId}/members/{memberId}`. This would be pointing to a specific member's record within a specific organization, with both `{orgID}` and `{memberID}` requiring variables.

Path vs query parameters

Path parameter values are perhaps not as exciting and customizable as query parameters, but no matter how cleverly you query, you won't find a resource if you're looking in the wrong place! Path parameters offer a very human-readable way of understanding a resource location, similar to a local file location like `C:/Program Files/Program`. It's where we want to look for key-value pairs from the request header.

Path parameter API tutorial

Let's say we want to [call](/what-is-an-api-call.md) a weather API for our daily surf report:

```java curl /surfreport/beachId?days=3&units=metric&time=1400```

What do we see in this GET request?  

  • `/surfreport/{beachID}` `/surfreport` is the endpoint, and `beachID` is the path parameter. The `/surfreport/{beachID}` path parameter takes a geographic beach code to look up the resource associated with that code.
  • `?` is where our query string begins. This information is returned in a JSON file.

Conclusion

While query parameters describe how to look, path parameters show your program where to look. Path parameters are part of the endpoint URI and are required to have a value. Think of path parameters as the file system in your endpoint URL, guiding the request to the answer it seeks.