Skip to main content
Version: 5.2

Resource

Resource is an Entity with multiple Endpoints that operate on the data. All additional members are provided to make CRUD or other REST-like API definitions easy and terse.

For other patterns, feel free to use Endpoints on their own or in any other way you see fit.

import { Resource } from '@rest-hooks/rest';

export default class ArticleResource extends Resource {
  readonly id: number | undefined = undefined;
  readonly title: string = '';
  readonly content: string = '';
  readonly author: number | null = null;
  readonly tags: string[] = [];

  pk() {
    return this.id?.toString();
  }

  static urlRoot = 'http://test.com/article/';
}
extends

Resource extends BaseResource

Package: @rest-hooks/rest

There are two sides to Resource definition - the static and instance side.

Static​

Is used to define how you retrieve and mutate data across the network. There are several static methods that do this, but their ultimate purpose is to build Endpoints, which tell the hooks how to process requests. Endpoints are provided for the common REST request types. However, it is encouraged to build your own or override the provided ones to fit the needs of your API.

Resource extends from BaseResource which extends from Entity, which includes many static methods defining how to process network data to ensure performance and consistency. Deserilization for instance can be done using the static schema.

Instance​

Instances are mostly for you to define how you want to interact with your data. This means you should start off by defining the fields you expect to see, and provide defaults in case they are not sent for some reason. Resource also requires that you define a method to get an entity's (entity is an instance of a Resource) unique identifier. (This is used for book-keeping the normalized cache.) Make sure to mark all members as readonly as all the data members are immutable (this library enforces that)!

You are encouraged to add your own member methods. Often times it is useful to provide methods for computed values that are commonly used in your React components.

A final note: Resource provides a factory method called fromJS() that will be used to construct instances. This is the only supported way of created Resources so please don't use constructors.

Factory method​

fromJS(props): Resource​

Inherited from Entity

static fromJS<T extends typeof SimpleRecord>(this: T, props: Partial<AbstractInstanceType<T>>): AbstractInstanceType<T>

Factory method called during denormalization. Use this instead of new MyEntity()

Be sure to always provide:​

pk: (parent, key) => string​

Inherited from Entity

PK stands for primary key and is intended to provide a standard means of retrieving a key identifier for any Resource. In many cases there will simply be an 'id' field member to return. In case of multicolumn you can simply join them together.

Multi-column primary key:​

Sometimes you have a resource that doesn't have its own primary key. This is typically found in join tables that express many-to-many relationships.

export class VoteResource extends Resource {
  readonly userId: number | undefined = undefined;
  readonly postId: number | undefined = undefined;
  readonly createdAt: string = '1900-01-01T01:01:01Z';

  pk() {
    return [this.userId, this.postId].join(',');
  }
  static urlRoot = 'https://example.com/votes/';
}

undefined value​

A undefined can be used as a default to indicate the resource has not been created yet. This is useful when initializing a creation form using Resource.fromJS() directly. If pk() resolves to null it is considered not persisted to the server, and thus will not be kept in the cache.

Other uses​

While the pk() definition is key (pun intended) for making the normalized cache work; it also becomes quite convenient for sending to a react element when iterating on list results:

//....
return (
  <div>
    {results.map(result => (
      <TheThing key={result.pk()} thing={result} />
    ))}
  </div>
);

Singleton Resources​

What if there is only ever once instance of a Resource for your entire application? You don't really need to distinguish between each instance, so likely there was no id or similar field defined in the API. In these cases you can just return a literal like 'the_only_one'.

pk() {
  return 'the_only_one';
}

static urlRoot: string​

Used to build url patterns in url() and listUrl(). Used as the default in key so typically you'll want this to be globally unique per Resource.

static get key(): string​

Inherited from Entity

This defines the key for the Resource itself, rather than an instance. As seen below, by default it simply returns the urlRoot since this is typically globally unique. However if you want to share urlRoot across different Resources, be sure to override this.

/** Returns the globally unique identifier for this Resource */
static get key(): string {
  return this.urlRoot;
}

Static network methods and properties​

These are the basic building blocks used to compile the Endpoint below.

static url(urlParams) => string​

Inherited from BaseResource

static url<T extends typeof Resource>(urlParams: Partial<AbstractInstanceType<T>>) => string

Computes the url based on the parameters. Default implementation follows /urlRoot/[pk] pattern.

Used in detail(), update(), partialUpdate(), and delete()

static listUrl(searchParams) => string​

Inherited from BaseResource

static listUrl(searchParams: Readonly<Record<string, string>>) => string

Computes url for retrieving list items. Defaults to urlRoot with searchParams being sent as GET parameters.

Used in list() and create()

static fetch(requestInfo, requestInit) => Promise​

Inherited from BaseResource

static fetch(info: RequestInfo, init: RequestInit) => Promise<any>

Performs the actual network fetch returning a promise that resolves to the network response or rejects on network error. This can be useful to override to really customize your transport.

static fetchResponse(requestInfo, requestInit) => Promise​

Inherited from BaseResource

static fetchResponse(info: RequestInfo, init: RequestInit) => Promise<any>

Used in fetch(). Resolves the HTTP Response.

static getFetchInit(init: RequestInit): RequestInit​

Inherited from BaseResource

Allows simple overrides to extend RequestInit sent to fetch. This is called during the fetch callback. Don't use hooks here.

This is often useful for authentication

static getEndpointExtra() => EndpointExtraOptions | undefined​

Inherited from BaseResource

Returns the default request options for this resource. By default this returns undefined

Endpoints​

These provide the standard CRUD endpointss common in REST APIs. Feel free to customize or add new endpoints based to match your API.

detail(): Endpoint​

A GET request using standard url() that receives a detail body. Mostly useful with useSuspense

  • Uses url()
  • Compatible with all hooks

Implementation:​

static detail<T extends typeof SimpleResource>(this: T) {
  return this.memo('#detail', () =>
    this.endpoint().extend({
      schema: this as SchemaDetail<Readonly<AbstractInstanceType<T>>>,
    }),
  );
}

list(): Endpoint​

A GET request using listUrl() that receives a list of entities. Mostly useful with useSuspense

Implementation:​

static list<T extends typeof SimpleResource>(this: T) {
  return this.memo('#list', () =>
    this.endpoint().extend({
      schema: [this] as SchemaList<Readonly<AbstractInstanceType<T>>>,
      url: this.listUrl.bind(this),
    }),
  );
}

create(): Endpoint​

A POST request sending a payload to listUrl() with empty params, and expecting a detail body response. Mostly useful with Controller.fetch

Uses listUrl()

Not compatible with:

Implementation:​

static create<T extends typeof SimpleResource>(this: T) {
  return this.memo('#create', () =>
    this.endpointMutate().extend({
      schema: this as SchemaDetail<Readonly<AbstractInstanceType<T>>>,
      url: this.listUrl.bind(this),
    }),
  );
}

update(): Endpoint​

A PUT request sending a payload to a url() expecting a detail body response. Mostly useful with Controller.fetch

Uses url()

Not compatible with:

Implementation:​

static update<T extends typeof SimpleResource>(this: T) {
  return this.memo('#update', () =>
    this.endpointMutate().extend({
      method: 'PUT',
      schema: this as SchemaDetail<Readonly<AbstractInstanceType<T>>>,
    }),
  );
}

partialUpdate(): Endpoint​

A PATCH request sending a partial payload to url() expecting a detail body response. Mostly useful with Controller.fetch

Uses url()

Not compatible with:

Implementation:​

static partialUpdate<T extends typeof SimpleResource>(this: T) {
  return this.memo('#partialUpdate', () =>
    this.endpointMutate().extend({
      method: 'PATCH',
      schema: this as SchemaDetail<Readonly<AbstractInstanceType<T>>>,
    }),
  );
}

delete(): Endpoint​

A DELETE request sent to url() Mostly useful with Controller.fetch

Uses url()

Not compatible with:

Implementation:​

static delete<T extends typeof SimpleResource>(this: T) {
  const endpoint = this.endpointMutate();
  return this.memo('#delete', () =>
    endpoint.extend({
      fetch(params: Readonly<object>) {
        return endpoint.fetch.call(this, params).then(() => params);
      },
      method: 'DELETE',
      schema: new schema.Delete(this),
    }),
  );
}