Built-in factories for Mutations ​

JSON API ​

Since Farfetched provides createJsonQuery to create Queries that work with JSON API, it also provides createJsonMutation to create Mutations that work with JSON API.

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

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

const loginMutation = createJsonMutation({
  params: declareParams<{ login: string; password: string }>(),
  request: {
    method: 'POST',
    url: 'https://api.salo.com/login',
    body: ({ login, password }) => ({ credentials: { login, password } }),
  },
  response: {
    contract: unknownContract,
    status: { expected: 204 },
  },
});

Parameters declaration ​

Parameters declaration is the same as in createJsonQuery, it is literally the same function.

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, in our case it is just a static string.
• request.body is a function to formulate request body based on the parameters. It is optional, and if it is not provided, the request will not have a body.

const loginMutation = createJsonMutation({
  params: declareParams<{ login: string; password: string }>(),
  request: {
    method: 'POST',
    url: 'https://api.salo.com/login',
    body: ({ login, password }) => ({ credentials: { login, password } }),
  },
  response: {
    contract: unknownContract,
    status: { expected: 204 },
  },
});

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. In our case, we use unknownContract to say that we don't know the shape of the response, and we don't care about it.
• response.status.expected is used to describe the status of the response, it has to be an object with expected field that has to be a number or array of numbers. In our case, we expect that the response will have status 204.

const loginMutation = createJsonMutation({
  params: declareParams<{ login: string; password: string }>(),
  request: {
    method: 'POST',
    url: 'https://api.salo.com/login',
    body: ({ login, password }) => ({ credentials: { login, password } }),
  },
  response: {
    contract: unknownContract,
    status: { expected: 204 },
  },
});

What's else? ​

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

• Add Content-Type: application/json header to the request
• Parse the response as JSON (if the response has a body)

Custom factories ​

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

Read more about it in custom factories' recipe.