Building a REST API

In this tutorial you will create a REST API for a URL Shortener service. In a few short minutes, you'll learn how to:

• Create REST APIs with Encore
• Use PostgreSQL databases
• Use the local development dashboard to test your app
• Create and run tests

This is the end result:

1. Create a service and endpoint

Create a new application by running encore app create and select Empty app as the template.

If this is the first time you're using Encore, you'll be asked if you wish to create a free account. This is needed when you want Encore to manage functionality like secrets and handle cloud deployments (which we'll use later on in the tutorial).

Now let's create a new url service.

🥐 In your application's root folder, create a directory named url containing a file named encore.service.ts.

$ mkdir url
$ touch url/encore.service.ts

🥐 Add the following code to url/encore.service.ts:

url/encore.service.ts
import { Service } from "encore.dev/service";

export default new Service("url");

This is how you define a service with Encore. Encore will now consider files in the url directory and all its subdirectories as part of the url service.

🥐 Create a new file url.ts in the url directory:

$ touch url/url.ts

🥐 Add the following code to url/url.ts:

url/url.ts
import { api } from "encore.dev/api";
import { randomBytes } from "node:crypto";

interface URL {
  id: string; // short-form URL id
  url: string; // complete URL, in long form
}

interface ShortenParams {
  url: string; // the URL to shorten
}

// Shortens a URL.
export const shorten = api(
  { method: "POST", path: "/url", expose: true },
  async ({ url }: ShortenParams): Promise<URL> => {
    const id = randomBytes(6).toString("base64url");
    return { id, url };
  },
);

This sets up the POST /url endpoint.

🥐 Let’s see if it works! Start your app by running the following command from your app's root directory:

$ encore run

You should see this:

Encore development server running!

Your API is running at:     http://127.0.0.1:4000
Development Dashboard URL:  http://localhost:9400/5g288
3:50PM INF registered API endpoint endpoint=shorten path=/url service=url

🥐 Next, call your endpoint from the Local Development Dashboard at http://localhost:9400 and view a trace of the response. It should look like this:

You can also call it from the terminal:

$ curl http://localhost:4000/url -d '{"url": "https://encore.dev"}'

You should see this:

{
  "id": "5cJpBVRp",
  "url": "https://encore.dev"
}

It works! There’s just one problem...

Right now, we’re not actually storing the URL anywhere. That means we can generate shortened IDs but there’s no way to get back to the original URL! We need to store a mapping from the short ID to the complete URL.

2. Save URLs in a database

Fortunately, Encore makes it really easy to set up a PostgreSQL database to store our data. To do so, we first define a database schema, in the form of a migration file.

🥐 Create a new folder named migrations inside the url folder. Then, inside the migrations folder, create an initial database migration file named 001_create_tables.up.sql. The file name format is important (it must start with 001_ and end in .up.sql).

$ mkdir url/migrations
$ touch url/migrations/001_create_tables.up.sql

🥐 Add the following contents to the file:

url/migrations/001_create_tables.up.sql
CREATE TABLE url (
	id TEXT PRIMARY KEY,
	original_url TEXT NOT NULL
);

🥐 Next, go back to the url/url.ts file and import the SQLDatabase class from encore.dev/storage/sqldb module by modifying the imports to look like this:

url/url.ts
import { api } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";
import { randomBytes } from "node:crypto";

🥐 Now, to define the database, create an instance of the SQLDatabase class in the url service:

url/url.ts
import { api } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";
import { randomBytes } from "node:crypto";

// 'url' database is used to store the URLs that are being shortened.
const db = new SQLDatabase("url", { migrations: "./migrations" });

interface URL {
    id: string; // short-form URL id
    url: string; // complete URL, in long form
}

interface ShortenParams {
    url: string; // the URL to shorten
}

// Shortens a URL.
export const shorten = api(
    { method: "POST", path: "/url", expose: true },
    async ({ url }: ShortenParams): Promise<URL> => {
        const id = randomBytes(6).toString("base64url");
        return { id, url };
    },
);

🥐 Lastly, update the shorten function to insert data into the database:

url/url.ts
import { api } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";
import { randomBytes } from "node:crypto";

// 'url' database is used to store the URLs that are being shortened.
const db = new SQLDatabase("url", { migrations: "./migrations" });

interface URL {
    id: string; // short-form URL id
    url: string; // complete URL, in long form
}

interface ShortenParams {
    url: string; // the URL to shorten
}

// Shortens a URL.
export const shorten = api(
    { method: "POST", path: "/url", expose: true },
    async ({ url }: ShortenParams): Promise<URL> => {
      const id = randomBytes(6).toString("base64url");
      await db.exec`
        INSERT INTO url (id, original_url)
        VALUES (${id}, ${url})
      `;
      return { id, url };
    },
  );

🥐 Next, start the application again with encore run and Encore automatically sets up your database.

(In case your application won't run, check the databases troubleshooting guide.)

You can verify that the database was created by looking at the Infra tab in the local development dashboard at localhost:9400, which should look like this:

🥐 Now let's call the API again from the local development dashboard, or from the terminal:

$ curl http://localhost:4000/url -d '{"url": "https://encore.dev"}'

🥐 Finally, let's verify that it was saved in the database. You can do this by checking the trace in the local development dashboard, or you can run encore db shell url from the app root directory and inputting select * from url;:

$ encore db shell url
psql (13.1, server 11.12)
Type "help" for help.
url=# select * from url;
    id    |    original_url
----------+--------------------
 zr6RmZc4 | https://encore.dev
(1 row)

That was easy!

3. Add endpoint to retrieve URLs

To complete our URL shortener API, let’s add the endpoint to retrieve a URL given its short id.

🥐 Add this endpoint to url/url.ts:

url/url.ts
import { api, APIError } from "encore.dev/api";
import { SQLDatabase } from "encore.dev/storage/sqldb";
import { randomBytes } from "node:crypto";

// 'url' database is used to store the URLs that are being shortened.
const db = new SQLDatabase("url", { migrations: "./migrations" });

interface URL {
    id: string; // short-form URL id
    url: string; // complete URL, in long form
}

interface ShortenParams {
    url: string; // the URL to shorten
}

// Shortens a URL.
export const shorten = api(
    { method: "POST", path: "/url", expose: true },
    async ({ url }: ShortenParams): Promise<URL> => {
      const id = randomBytes(6).toString("base64url");
      await db.exec`
        INSERT INTO url (id, original_url)
        VALUES (${id}, ${url})
      `;
      return { id, url };
    },
  );

  // Get retrieves the original URL for the id.
export const get = api(
    { expose: true, auth: false, method: "GET", path: "/url/:id" },
    async ({ id }: { id: string }): Promise<URL> => {
      const row = await db.queryRow`
          SELECT original_url FROM url WHERE id = ${id}
      `;
      if (!row) throw APIError.notFound("url not found");
      return { id, url: row.original_url };
    }
  );

Encore uses the /url/:id syntax to represent a path with a parameter. The id name corresponds to the parameter name in the function signature. In this case it is of type string, but you can also use other built-in types like number or boolean if you want to restrict the values.

🥐 We can make sure it works by reviewing the endpoint in the Service Catalog in the local development dashboard, where we can call it using the id you got in the previous step:

You can also call it directly from the terminal:

$ curl http://localhost:4000/url/your-id-from-the-previous-step

You should now see this:

{
  "id": "your-id-from-the-previous-step",
  "url": "https://encore.dev"
}

It works! That's how you build REST APIs and use PostgreSQL databases in Encore.

4. Add a test

Before deployment, it is good practice to have tests to assure that the service works properly. Such tests including database access are easy to write.

🥐 Let's start by adding the vitest package to your project:

$ npm i --save-dev vitest

Vitest is a testing framework that works great with Encore but you can use another TypeScript testing framework if you like.

🥐 Next we need to add a test script to our package.json:

package.json
"scripts": {
  "test": "vitest"
},

We've prepared a test to check that the whole cycle of shortening the URL, storing and then retrieving the original URL works.

🥐 Save this in a separate file url/url.test.ts.

url/url.test.ts
import { describe, expect, test } from "vitest";
import { get, shorten } from "./url";

describe("shorten", () => {
  test("getting a shortened url should give back the original", async () => {
    const resp = await shorten({ url: "https://example.com" });
    const url = await get({ id: resp.id });
    expect(url.url).toBe("https://example.com");
  });
});

🥐 Now run encore test to verify that it's working.

If you use the local development dashboard (localhost:9400), you can even see traces for tests.

5. Deploy

What's next

Now that you know how to build a backend with a database, you're ready to let your creativity flow and begin building your next great idea!

We're excited to hear what you're going to build with Encore, join the pioneering developer community on Discord and share your story.