# "api" object

{% hint style="info" %}
🎥 Watch the "api" object section of the ["Server Global State (TanStack/React Query)"](https://youtu.be/f-UX9pu7u9Y) style guide video here.
{% endhint %}

***

We use a [custom-built **"api" object**](https://youtu.be/lux6vB4GyWk?si=YPnseIcBPZUjkZxy), which is essentially a wrapper over [React Query](https://tanstack.com/query/v3/)[ (v3)](https://tanstack.com/query/v3/), and is [tRPC-like](https://create.t3.gg/en/usage/trpc) in terms of usage.

The frontend routes line up with our backend routes according to our [(v2) API schema](../../../api).\
\
&#xNAN;_(in the comments in the second image below, you can see which backend/Rails controller actions are related to each frontend route)_

***

### Overview

* [**Configuration**](#configuration)
* [**Usage**](#usage)

***

### Configuration

**"api" object** (holds "router" objects)

<figure><img src="https://2248755224-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkVQm1PpPMvCvQccIZPyj%2Fuploads%2FQLuGVjqPUey4er4HbHXQ%2FCleanShot%202023-11-10%20at%2013.57.12%402x.png?alt=media&#x26;token=3d42bbe9-ec11-464d-b73d-31017a5ed973" alt=""><figcaption></figcaption></figure>

**"router" objects** (hold **"procedures"** -- e.g. getSingle, getMany, etc.)

<figure><img src="https://2248755224-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkVQm1PpPMvCvQccIZPyj%2Fuploads%2FVQeJQPM8ALN4LkUICXaL%2FCleanShot%202023-11-10%20at%2013.57.35%402x.png?alt=media&#x26;token=969b7bab-8e01-44ed-8561-b38c0e24feef" alt=""><figcaption></figcaption></figure>

***

### Usage

* **Queries (e.g. getSingle, getMany) (useQuery-wrapped procedures)**

<figure><img src="https://2248755224-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkVQm1PpPMvCvQccIZPyj%2Fuploads%2F8IH2p1KZQb7lDIRtkeJD%2FCleanShot%202023-11-10%20at%2014.00.38%402x.png?alt=media&#x26;token=611aea59-1faf-4813-9c8b-d74c1f2fd0b9" alt=""><figcaption></figcaption></figure>

* **Mutations (e.g. create, update, delete) (useMutation-wrapped procedures)**

<figure><img src="https://2248755224-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkVQm1PpPMvCvQccIZPyj%2Fuploads%2FtYfRO9nCIYFVsxk3IFIE%2FCleanShot%202023-11-10%20at%2014.03.11%402x.png?alt=media&#x26;token=0d9a9266-db78-4be5-a301-10813b1f4975" alt=""><figcaption></figcaption></figure>

**-- Top-level resource (e.g. projects):**

<figure><img src="https://2248755224-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkVQm1PpPMvCvQccIZPyj%2Fuploads%2FIN1qWjusLlUFbGQM1RsH%2FCleanShot%202023-11-10%20at%2014.03.49%402x.png?alt=media&#x26;token=cfb28cd1-2d11-4bc9-8721-59e4a2805501" alt=""><figcaption></figcaption></figure>

```jsx
mutationProjectUpdate.mutate({
  id: doc.id,
  payload: {
    production_goal: requestData.production_goal,
  },
});
```

**-- Nested resource (e.g. production goals -- projects/production\_goals)**

<figure><img src="https://2248755224-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkVQm1PpPMvCvQccIZPyj%2Fuploads%2FbjEQ4CtrQDghhFay51SE%2FCleanShot%202023-11-10%20at%2014.04.39%402x.png?alt=media&#x26;token=a9976fb2-8d7b-475b-9c7e-6abfc7dfd1d2" alt=""><figcaption></figcaption></figure>

```jsx
mutationProductionUpdate.mutate({
  parentResource: 'projects',
  parentId: doc.id,
  id: production.id,
  payload: {
    date: production.date,
    goal: production.goal,
    actual: production.actual,
  },
});
```
