Built-in factories for Mutations
You will learn
- Why do we need built-in factories
- How to use built-in factories
- How to create your own factory
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
orPOST
.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 useunknownContract
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 withexpected
field that has to be a number or array of numbers. In our case, we expect that the response will have status204
.
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.