Parameters

In Hyper Fetch, parameters are crucial for creating dynamic and flexible requests. They allow you to pass data to your API endpoints as part of the URL path. This guide covers everything you need to know about defining and using URL parameters effectively. For query parameters, see our dedicated guide.

What you'll learn

1. How to define and use URL path parameters.
2. What is the difference between .setParams() and passing parameters to the .send() method.
3. What are the precedence rules when setting parameters in multiple ways.

---

URL Parameters

URL parameters are placeholders in the endpoint string, prefixed with a colon :, like :userId. Hyper Fetch automatically detects these, providing type-safety and ensuring they are replaced with actual values when a request is made.

Setting with setParams

The setParams method is the most direct way to set URL parameters. The required parameters are inferred from the endpoint string, giving you strong type-safety.

const getUser = client.createRequest()({ endpoint: "/users/:userId" });

const requestWithUser = getUser.setParams({ userId: 281 });

console.log(requestWithUser.endpoint); // "/users/281"

If an endpoint has multiple parameters, you provide them all to setParams.

const getProduct = client.createRequest()({ endpoint: "/entities/:categoryId/:productId" });

const requestWithProduct = getProduct.setParams({ categoryId: 12, productId: "Z24PBW443" });

console.log(requestWithProduct.endpoint); // "/entities/12/Z24PBW443"

Setting with send

You can also pass parameters directly to the send method. This is useful when parameters are determined at runtime, just before sending the request.

const getProduct = client.createRequest()({ endpoint: "/entities/:categoryId/:productId" });

// Parameters are passed inside the `send` method's options
const response = getProduct.send({
  params: { categoryId: 12, productId: "Z24PBW443" },
});

---

Parameter Precedence

It's important to understand what happens when you set parameters in multiple places. Hyper Fetch does not allow you to pass parameters that are already defined in the request.

If you ignore Typescript - parameters passed directly to send will always override those set with setParams or setQueryParams.

const request = client
  .createRequest<{ queryParams: { page: number } }>()({ endpoint: "/users/:userId" })
  .setParams({ userId: 1 })
  .setQueryParams({ page: 1 });

console.log("Initial params:", request.params); // { userId: 1 }
console.log("Initial query params:", request.queryParams); // { page: 1 }

// Parameters given to `send` will override previously set ones.
request.send({
  // Typescript will not allow you to pass a parameter that is already defined in the request
  params: { userId: 2 },
  // Typescript will not allow you to pass a query parameter that is already defined in the request
  queryParams: { page: 2 },
});

---

Congratulations!

You've now mastered how to handle parameters in Hyper-Fetch.

• You can define URL Parameters with :param in the endpoint and set with .setParams({ param: ... }).
• You can set parameter types dynamically within the .send() method.
• You know that parameters from the .send() method always override those set with .set...() methods.
• You can leverage type-safety to prevent common bugs and improve code quality.