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

If you haven't already, 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 new folder url and create a new file url.go that looks like this:

// Service url takes URLs, generates random short IDs, and stores the URLs in a database.
package url

import (
	"context"
	"crypto/rand"
	"encoding/base64"
)

type URL struct {
	ID  string // short-form URL id
	URL string // complete URL, in long form
}

type ShortenParams struct {
	URL string // the URL to shorten
}

// Shorten shortens a URL.
//encore:api public method=POST path=/url
func Shorten(ctx context.Context, p *ShortenParams) (*URL, error) {
	id, err := generateID()
	if err != nil {
		return nil, err
	}
	return &URL{ID: id, URL: p.URL}, nil
}

// generateID generates a random short ID.
func generateID() (string, error) {
	var data [6]byte // 6 bytes of entropy
	if _, err := rand.Read(data[:]); err != nil {
		return "", err
	}
	return base64.RawURLEncoding.EncodeToString(data[:]), nil
}

This sets up the POST /url endpoint (see the //encore:api annotation on the Shorten function).

🥐 Let’s see if it works! Start your app by running encore run.

You should see this:

Your API is running at:     http://localhost:4000
Development Dashboard URL:  http://localhost:9400
4:19PM INF registered endpoint path=/url service=url endpoint=Shorten

🥐 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"}'

And 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 1_create_tables.up.sql. The file name format is important (it must start with 1_ and end in .up.sql).

🥐 Add the following contents to the file:

CREATE TABLE url (
	id TEXT PRIMARY KEY,
	original_url TEXT NOT NULL
);

🥐 Next, go back to the url/url.go file and import the encore.dev/storage/sqldb package by modifying the import statement to become:

import (
	"context"
	"crypto/rand"
	"encoding/base64"

	"encore.dev/storage/sqldb"
)

🥐 Then let's define our database object by adding the following to url/url.go:

// Define a database named 'url', using the database
// migrations in the "./migrations" folder.

var db = sqldb.NewDatabase("url", sqldb.DatabaseConfig{
	Migrations: "./migrations",
})

🥐 Now, to insert data into our database, let’s create a helper function insert:

// insert inserts a URL into the database.
func insert(ctx context.Context, id, url string) error {
	_, err := db.Exec(ctx, `
        INSERT INTO url (id, original_url)
        VALUES ($1, $2)
    `, id, url)
	return err
}

🥐 Lastly, we can update our Shorten function to insert into the database:

func Shorten(ctx context.Context, p *ShortenParams) (*URL, error) {
	id, err := generateID()
	if err != nil {
		return nil, err
	} else if err := insert(ctx, id, p.URL); err != nil {
		return nil, err
	}
	return &URL{ID: id, URL: p.URL}, nil
}

🥐 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 your application's Flow architecture diagram 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.go:

// Get retrieves the original URL for the id.
//encore:api public method=GET path=/url/:id
func Get(ctx context.Context, id string) (*URL, error) {
	u := &URL{ID: id}
	err := db.QueryRow(ctx, `
        SELECT original_url FROM url
        WHERE id = $1
    `, id).Scan(&u.URL)
	return u, err
}

Encore uses the path=/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 int or bool 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/zr6RmZc4

You should now see this:

{
  "ID": "zr6RmZc4",
  "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.

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

package url

import (
	"context"
	"testing"
)

// TestShortenAndRetrieve - test that the shortened URL is stored and retrieved from database.
func TestShortenAndRetrieve(t *testing.T) {
	testURL := "https://github.com/encoredev/encore"
	sp := ShortenParams{URL: testURL}
	resp, err := Shorten(context.Background(), &sp)
	if err != nil {
		t.Fatal(err)
	}
	wantURL := testURL
	if resp.URL != wantURL {
		t.Errorf("got %q, want %q", resp.URL, wantURL)
	}

	firstURL := resp
	gotURL, err := Get(context.Background(), firstURL.ID)
	if err != nil {
		t.Fatal(err)
	}
	if *gotURL != *firstURL {
		t.Errorf("got %v, want %v", *gotURL, *firstURL)
	}
}

🥐 Save this in a separate file url/url_test.go.

🥐 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 to the cloud

The final step before you deploy is to commit all changes to the project repo.

🥐 Commit the new files to the project's git repo and trigger a deploy to Encore's free development cloud by running:

$ git add -A .
$ git commit -m 'Initial commit'
$ git push encore

Encore will now build and test your app, provision the needed infrastructure, and deploy your application to the cloud.

After triggering the deployment, you will see a URL where you can view its progress in the Encore Cloud dashboard. It will look something like: https://app.encore.cloud/$APP_ID/deploys/...

From there you can also see metrics, traces, and connect your own AWS or GCP account to use for production deployment.

Now you have a fully fledged backend running in the cloud, well done!

Celebrate with fireworks

Now that your app is running in the cloud, let's celebrate with some fireworks:

🥐 In the Cloud Dashboard, open the Command Menu by pressing Cmd + K (Mac) or Ctrl + K (Windows/Linux).

From here you can easily access all Cloud Dashboard features and for example jump straight to specific services in the Service Catalog or view Traces for specific endpoints.

🥐 Type fireworks in the Command Menu and press enter. Sit back and enjoy the show!

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!

🥐 A great next step is to integrate with GitHub. Once you've linked with GitHub, Encore will automatically start building and running tests against your Pull Requests.

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