API Client

Throughout this guide we will separate our actions in three:

Hydration
Read
Mutation

We will define each one in their sections.

Hydration

The Hydration is the process to fill the cache with the data you previously got.

import { api } from 'coreql';

const data = await api.resourceName
  .find(1)
  .hydrate({ data: { id: 1, attributes: { text: 'This is a sample' } } });

This will fill the cache with the key resource-name/1 with the value { id: 1, attributes: { text: "This is a sample" } }. CoreQL will then proceed to revalidate this resource again the backend to ensure we have the latest and most correct data from the API if there is a React component consuming it.

This also means we can miss data in our hydration and CoreQL will get that data later, in our example above we miss the key type inside the data and outside attributes, and probably a lot more attributes.

We could also hydrate the list of a resource.

import { api } from 'coreql';

const data = await api.resourceName.hydrate({
  data: [{ id: 1, attributes: { text: 'This is a sample' } }],
});

Now we will fill the key resource-name with an array of a single element.

Read

The Read process is when we want to access some resource, there are two ways to do this, using the API Client or using the React integration, the later is the recommended way if you are reading data inside React.

If you are not reading inside a React component then you should use the API Client read methods.

import { api } from 'coreql';

const collection = await api.resourceName.read();
const resource = await api.resourceName.find(1).read();

After fetching data this way the API Client will populate the cache calling the hydrate method, this way once you read the same data from React it will have it already prefetched, use this as a way to prefetch data before or while rendering a component.

Mutation

The Mutation process is the more complex one, here is where we will Create, Update and Delete data, all of this will be done using the API Client.

Create

If you want to create a new resource then you should use the create function of the API Client.

import { api } from 'coreql';

const data = await api.resourceName.create({ text: 'This is a sample' });

After calling create you will receive the results of the API, something similar to this JSON:

{
  "data": {
    "id": 1,
    "type": "resource-name",
    "attributes": {
      "text": "This is a sample"
    }
  }
}

Additionally create will call hydrate against this same resource to fill the cache, this way once you render a component using the new resource it will render immediately. This happens since most of the time after creating a new resource you want to show it to the user immediately.

Update

If you want to update an existing resource then you should use the update function of the API Client.

import { api } from 'coreql';

const data = await api.resourceName
  .find(1)
  .update({ text: 'This is a sample' });

After calling update you will receive the results of the API, something similar to this JSON:

{
  "data": {
    "id": 1,
    "type": "resource-name",
    "attributes": {
      "text": "This is a sample"
    }
  }
}

Additionally update will call hydrate against this same resource to update or fill the cache, this way once you render a component using this resource it will render immediately. This happens since most of the time when updating a resource you are already showing it or want to show it to the user.

Relationships

The relations between objects in the Core HTTP API is handled by the JSON:API spec especially, to update a relationship you will need to use the relation method of the API Client.

import { api } from 'coreql';

await api.resourceName
  .find(1)
  .update.relation('owner', { type: 'users', id: 2 });

This will update the relation owner of the resource with ID 1 to point to the users resource with the ID 2.

Delete

If you want to delete an existing resource then you should use the destroy function of the API Client.

import { api } from 'coreql';

await api.resourceName.find(1).destroy();

The destroy method returns undefined since there will be no data.

Additionally destroy will call hydrate against this same resource to replace it with {}, this way if a React component is showing it, it will be updated to null and stop rendering and old resource.

#Hydration

#Read

#Mutation

#Create

#Update

#Relationships