REST · Netzo

The REST module provides an HTTP API to interact with NetzoDB via RESTful operations. NetzoDB is built on top of Deno KV. Deno KV is a key-value database built directly into the runtime and instantly available in the Deno.Kv namespace. It can be used for many kinds of data storage use cases, but excels at storing simple data structures that benefit from very fast reads and writes. Netzo adds a few features on top of Deno KV to make it even more powerful and easy to use for every app you build with Netzo.

Usage

Registration

Configure the app in a netzo.config.ts configuration file as shown below.

Note that at least one endpoint must be registered to enable the REST module.

netzo.config.ts

import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.rest({
      apiKey: Deno.env.get("NETZO_API_KEY"),
      collections: [
        { name: "accounts" },
      ],
    }),
  ],
});

To skip API key authentication during development set the apiKey property to undefined as shown below.

export default defineConfig({
  plugins: [
    netzo.rest({
      apiKey: Deno.env.get("DENO_REGION") ? Deno.env.get("NETZO_API_KEY") : undefined,
      collections: [...],
    }),
  ],
});

Configuration

export type RestConfig = {
  /** Wether to require authentication using the provided API key in the
   * "x-api-key" header or "apiKey" query parameter. To disable authentication
   * set to `undefined`, otherwise it is recommended to set using Deno.env.get().
   * Defaults to Deno.env.get("NETZO_API_KEY"). */
  apiKey?: string;
  /** An array of database collections. */
  collections: {
    /** The name of the collection e.g. "users" `/rest/users`. */
    name: string;
    /** The methods to enable. Defaults to all methods. */
    methods?: ("find" | "get" | "create" | "update" | "patch" | "remove")[];
  }[];
};

Operations

Operation	HTTP Method	REST API Path	Deno KV Operation
find	`GET`	`/rest?$prefix=<PREFIX>`	list
get	`GET`	`/rest?$key=<KEY>`	get
create	`POST`	`/rest?$prefix=<PREFIX>`	set
update	`PUT`	`/rest?$key=<KEY>`	set
patch	`PATCH`	`/rest?$key=<KEY>`	set
remove	`DELETE`	`/rest?$key=<KEY>`	delete

`find`

Retrieves a list of all matching resources from the service.

const response = await fetch('/rest/todos')
const todos = await response.json()

Using query parameters to filter the list of resources e.g. by value of completed.

const responseCompleted = await fetch('/rest/todos?completed=true')
const todosCompleted = await responseCompleted.json()

`get`

Retrieve a single resource from the service.

const response = await fetch(`/rest/todos/${ID}`)
const todo = await response.json()

`create`

Create a new resource with data or multiple resources by passing in an array as data.

idField defaults to "id" and value to crypto.randomUUID() If idField is not provided as third argument, the default "id" will be used. Each data item can specify a value at that idField (or the default one), and if not provided, a random UUID will be generated for it via crypto.randomUUID() of the Web Crypto API.

const response = await fetch('/rest/todos', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    userId: '1',
    title: 'delectus aut autem',
    completed: false,
  })
})
const todo = await response.json()

const response = await fetch('/rest/todos', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify([
    {
      userId: 1,
      id: 1,
      title: 'delectus aut autem',
      completed: false
    },
    {
      userId: 1,
      id: 2,
      title: 'quis ut nam facilis et officia qui',
      completed: false
    },
    // ...
  ])
})
const todos = await response.json()

`update`

Completely replace a single resource.

const response = await fetch(`/rest/todos/${ID}`, {
  method: 'PUT',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    userId: '2',
    title: 'delectus aut autem',
    completed: true,
  })
})
const todo = await response.json()

`patch`

Merge the existing data of a single resource with the new data.

const response = await fetch(`/rest/todos/${ID}`, {
  method: 'PATCH',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    completed: true,
  })
})
const todo = await response.json()

`remove`

Remove a single resource.

const response = await fetch(`/rest/todos/${ID}`, {
  method: 'DELETE',
})
const { id } = await response.json()

Close Workspace

Auth

Built-in authentication, user management and role-based access control (RBAC).