Skip to main content
Version: 4.5

Resource

import { Resource } from 'rest-hooks';

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/';
}
import { Resource } from 'rest-hooks';

export default class ArticleResource extends Resource {
  id = undefined;
  title = '';
  content = '';
  author = null;
  tags = [];

  pk() {
    return this.id;
  }

  static urlRoot = 'http://test.com/article/';
}
import { Resource } from 'rest-hooks';

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

  pk() {
    return this.id;
  }

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

Resource extends Entity

Resource is an abstract class that will help you define the data you are working with. Resource aids in defining REST-like APIs - to implement other patterns, try building FetchShapes with Entity.

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 FetchShapes, which tell the hooks how to process requests. Shapes 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.

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​

static fromJS\<T extends typeof Resource>(this: T, props: Partial\<AbstractInstanceType\<T>>): AbstractInstanceType\<T>​

Inherited from SimpleRecord

This is used to create instances of the Resource you defined. Will copy over props provided to the instance in construction, among other things. Be sure to always call super.fromJS() when overriding.

Can be useful to override to:

Be sure to always provide:​

pk: (parent?: any, key?: string) => string | number | undefined​

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:​

pk(parent?: any, key?: string) {
  return [this.firstCol, this.secondCol, this.thirdCol].join(',');
}

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 Fetch shapes below.

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 detailShape(), updateShape() partialUpdateShape(), and deleteShape()

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 listShape() and createShape()

static fetch(method: "get" | "post" | "put" | "patch" | "delete" | "options", url: string, body?: Readonly\<object | string>) => 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(method: "get" | "post" | "put" | "patch" | "delete" | "options", url: string, body?: Readonly\<object | string>) => Promise\<Response>​

Used in fetch(). Resolves the HTTP Response.

static asSchema() => Entity​

Returns this Resource as an Entity with the TypeScript type set properly. Using asSchema() instead of this directly is key to getting correct typing from the hooks.

Use in schemas when referring to this Resource.

  static listShape<T extends typeof Resource>(this: T) {
    return {
      ...super.listShape(),
      schema: { results: [this.asSchema()], nextPage: '', prevPage: '' },
    };
  }

static getFetchOptions() => FetchOptions | undefined​

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

Fetch shapes​

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

detailShape(): ReadShape​

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

listShape(): ReadShape​

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

createShape(): MutateShape​

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

updateShape(): MutateShape​

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

partialUpdateShape(): MutateShape​

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

deleteShape(): DeleteShape​

A DELETE request sent to url() Mostly useful with useFetcher