complex-teal•2y ago

Clearing up usage/purpose of `custom` method parameters.

Hey. For the custom method in a data provider, what is the difference between query, payload, and meta parameters? What are they used for or what are their main purpose?

9 Replies

kapa.ai•2y ago

Hi @bombillazo. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- The custom method in a data provider allows you to handle requests with custom parameters like URL, CRUD methods, and configurations. It's useful for non-standard REST API endpoints or connecting with external resources. The query, payload, and meta parameters serve different purposes within the custom method: 1. query: This parameter is an object that represents the query parameters to be sent with the request. It can be used to pass additional data to the API endpoint. 2. payload: This parameter is an object that represents the request body to be sent with the request. It is typically used for POST, PUT, and PATCH requests to send data to the API endpoint. 3. meta: This parameter is used for two main purposes: - To pass additional information to data provider methods. - To generate GraphQL queries using plain JavaScript Objects (JSON). Here's an example of the custom method in a data provider:

custom: async ({  
 url,  
 method,  
 filters,  
 sorters,  
 payload,  
 query,  
 headers,  
 meta,  
}) => {  
 // You can handle the request according to your API requirements.  
  
 return {  
 data,  
 };  
};

custom: async ({  
 url,  
 method,  
 filters,  
 sorters,  
 payload,  
 query,  
 headers,  
 meta,  
}) => {  
 // You can handle the request according to your API requirements.  
  
 return {  
 data,  
 };  
};

For more information, refer to the Data Provider documentation (https://refine.dev/docs/api-reference/core/providers/data-provider). ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2y ago

<@260960777010151436> kapa.ai is still learning and improving, please let us how it did by reacting below

complex-teal•2y ago

@kapa.ai Can you give a more concrete example of the difference between query and payload?

kapa.ai•2y ago

Let me check the knowledge base for you. One moment! :books: ---------------------- Certainly! The query and payload parameters in the custom method of a data provider serve different purposes when making API requests. - query: This parameter is an object that represents the query parameters to be sent with the request. Query parameters are appended to the URL and are typically used for filtering, sorting, or pagination in GET requests. - payload: This parameter is an object that represents the request body to be sent with the request. It is used for sending data to the API endpoint, typically in POST, PUT, and PATCH requests. Here's a concrete example: Suppose you have an API endpoint for searching users with filters and you want to create a new user. For searching users, you would use a GET request with query parameters:

const { data, isLoading } = useCustom({  
 url: `${apiURL}/search-users`,  
 method: "get",  
 config: {  
   query: {  
     name: "John Doe",  
     age: 25,  
   },  
 },  
});

const { data, isLoading } = useCustom({  
 url: `${apiURL}/search-users`,  
 method: "get",  
 config: {  
   query: {  
     name: "John Doe",  
     age: 25,  
   },  
 },  
});

In this case, the query parameter is used to pass the search filters (name and age) as query parameters in the URL. For creating a new user, you would use a POST request with a payload:

const { mutate } = useCustomMutation();  

mutate({  
 method: "post",  
 url: `${apiURL}/create-user`,  
 config: {  
   payload: {  
     name: "Jane Doe",  
     age: 30,  
   },  
 },  
});

const { mutate } = useCustomMutation();  

mutate({  
 method: "post",  
 url: `${apiURL}/create-user`,  
 config: {  
   payload: {  
     name: "Jane Doe",  
     age: 30,  
   },  
 },  
});

In this case, the payload parameter is used to send the user data (name and age) in the request body. For more information, refer to the useCustom documentation (https://refine.dev/docs/api-reference/core/hooks/data/useCustom/). ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•2y ago

<@260960777010151436> kapa.ai is still learning and improving, please let us how it did by reacting below

complex-teal•2y ago

Cool, @kapa.ai how do I use the meta parameter in a DataProvider method? Give me an in-depth example.

kapa.ai•2y ago

Let me check the knowledge base for you. One moment! :books: ---------------------- The meta parameter is used to pass additional information to data provider methods. It can be useful for customizing the behavior of a specific method or passing extra data that is not part of the standard parameters. Here's an in-depth example of using the meta parameter in a custom method of a data provider: Suppose you have an API that requires a custom header for authentication, and you want to pass this header only for specific requests. You can use the meta parameter to achieve this. First, create a custom method in your data provider:

const myDataProvider = {
  //...
  custom: async ({
    url,
    method,
    payload,
    query,
    headers,
    meta,
  }) => {
    const customHeader = meta?.customHeader;
    const updatedHeaders = customHeader
      ? { ...headers, "x-custom-header": customHeader }
      : headers;

    // Make the API request with the updated headers
    //...

    return {
      data,
    };
  },
  //...
};

const myDataProvider = {
  //...
  custom: async ({
    url,
    method,
    payload,
    query,
    headers,
    meta,
  }) => {
    const customHeader = meta?.customHeader;
    const updatedHeaders = customHeader
      ? { ...headers, "x-custom-header": customHeader }
      : headers;

    // Make the API request with the updated headers
    //...

    return {
      data,
    };
  },
  //...
};

In this example, the custom method checks if the meta parameter contains a customHeader property. If it does, it adds the custom header to the request headers. Now, when you use the useCustom or useCustomMutation hooks, you can pass the meta parameter with the custom header:

const { data, isLoading } = useCustom({
  url: `${apiURL}/some-endpoint`,
  method: "get",
  config: {
    meta: {
      customHeader: "my-auth-token",
    },
  },
});

const { mutate } = useCustomMutation();

mutate({
  method: "post",
  url: `${apiURL}/another-endpoint`,
  config: {
    payload: {
      name: "John Doe",
      age: 25,
    },
    meta: {
      customHeader: "my-auth-token",
    },
  },
});

const { data, isLoading } = useCustom({
  url: `${apiURL}/some-endpoint`,
  method: "get",
  config: {
    meta: {
      customHeader: "my-auth-token",
    },
  },
});

const { mutate } = useCustomMutation();

mutate({
  method: "post",
  url: `${apiURL}/another-endpoint`,
  config: {
    payload: {
      name: "John Doe",
      age: 25,
    },
    meta: {
      customHeader: "my-auth-token",
    },
  },
});

In both cases, the meta parameter is used to pass the custom header to the custom method in the data provider, which then adds it to the request headers.

kapa.ai•2y ago

For more information, refer to the useCustom documentation (https://refine.dev/docs/api-reference/core/hooks/data/useCustom/) and useCustomMutation documentation (https://refine.dev/docs/api-reference/core/hooks/data/useCustomMutation/). ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

useCustom | refine

useCustom is an extended version of TanStack Query's useQuery. It supports all the features of useQuery and adds some extra features.

kapa.ai•2y ago

<@260960777010151436> kapa.ai is still learning and improving, please let us how it did by reacting below