Built-in factories for Query ​

createQuery is pretty powerful, it allows you to create any Query you want. But it's not always the best solution. Sometimes you just want to create a simple query, and you don't want to bother with all the details. That's why we have built-in factories.

JSON API ​

A lot of modern APIs work with JSON. It accepts JSON as input and returns JSON as output. It's a very convenient format, because it's easy to read and write. Not only that, but it's also very flexible, because it allows you to send only the data you need. So, Farfetch has a built-in factory for JSON API — createJsonQuery.

Let's start with an example, and then we'll explain what's going on.

import { createJsonQuery } from '@farfetched/core';

const characterQuery = createJsonQuery({
  params: declareParams<{ id: number }>(),
  request: {
    method: 'GET',
    url: ({ id }) => `https://rickandmortyapi.com/api/character/${id}`,
  },
  response: {
    contract: runtypeContract(Character),
  },
});

Parameters declaration ​

As you can see, it is no explicit handler here, however we still need to declare some parameters of the Query, Farfetched provides special helper for that — declareParams. It accepts a generic type which is type of parameters.

import { declareParams } from '@farfetched/core';

const characterQuery = createJsonQuery({
  params: declareParams<{ id: number }>(),
  request: {
    method: 'GET',
    url: ({ id }) => `https://rickandmortyapi.com/api/character/${id}`,
  },
  response: {
    contract: runtypeContract(Character),
  },
});

By default, createJsonQuery returns a Query without any parameters.

Request ​

request field of the config is dedicated to description of the request to the API. It has plenty fields, which are listed in the API reference, for now let's concentrate on the most important ones.

• request.method has to be a string with an HTTP method in uppercase, e.g. GET or POST.
• request.url is used to formulate a URL of the request, it could be declared in many forms, but two the most interesting for us:
  • just static string
  • function that accepts Query paramters and returns a string

const characterQuery = createJsonQuery({
  params: declareParams<{ id: number }>(),
  request: {
    method: 'GET',
    url: ({ id }) => `https://rickandmortyapi.com/api/character/${id}`,
  },
  response: {
    contract: runtypeContract(Character),
  },
});

Response ​

response field of the config is dedicated to description of the response from the API. It has plenty fields, which are listed in the API reference, for now let's concentrate on the most important ones.

• response.contract is used to describe the shape of the response, it has to be a Contract object.

const characterQuery = createJsonQuery({
  params: declareParams<{ id: number }>(),
  request: {
    method: 'GET',
    url: ({ id }) => `https://rickandmortyapi.com/api/character/${id}`,
  },
  response: {
    contract: runtypeContract(Character),
  },
});

What's else? ​

createJsonQuery does some additional job to make your life easier. It does the following:

• Add Content-Type: application/json header to the request
• Apply TAKE_LATEST strategy and cancel all previous requests, you can override this behavior by passing concurrency.strategy option to the factory
• Parse the response as JSON

Custom factories ​

Sometimes you need to create a bunch of Queries that are not covered by built-in factories and do not want to do the same job many times for every Query. In this case, you can create your own factory.

Read more about it in custom factories' recipe.