Time to REST with Encore v0.17

REST APIs, ORM and Query Helpers, and more!

Sep 20, 2021

André Eriksson

André is the founder of Encore and a long-time backend engineer. Before that he was a Staff Software Engineer at Spotify for 8 years.

We're excited to announce Encore v0.17, our most feature-packed and best release yet! If you'd like to give Encore a go for the first time, check out our quick start. If you already have Encore installed, you can update with encore version update.

The simplest way to build a REST API

We've heard you: the Encore developer experience is great, but building REST APIs was too cumbersome. No more! You can now define REST APIs with incredible speed and productivity, through the power of Encore's static analysis and code generation engine. Just take a look:

// The List endpoint returns a list of blog articles.
// It can be called simply as:
//
//     GET /blog?limit=30&offset=0
//
//encore:api public method=GET path=/blog
func List(ctx context.Context, p *ListParams) (*ListResponse, error) {
    // Fetch results...
}

// ListParams are the query parameters for the List endpoint.
type ListParams struct {
    Limit int
    Offset int
}

// ListResponse is the response schema for the List endpoint.
type ListResponse struct {
    Posts []*Post
}

If it looks just like regular, plain Go code, you'd be exactly right! Since it's a GET endpoint, Encore automatically parses the ListParams fields and parses them from the query string in the HTTP request.

This approach lets you think and develop your API in terms of functions and data structures, instead of worrying about low-level HTTP request parsing. The end result is a remarkably simple programming paradigm that dramatically increases productivity.

We call it the Encore Application Model — a combination of static analysis and code generation — and it's all about understanding what you're trying to do and helps you achieve it faster and easier than ever before. By taking all the boilerplate out of backend development we're left with a much more enjoyable developer experience as well.

ORM Support and Query Helpers

Encore's SQL Database support now works seamlessly with the large Go ecosystem of ORMs and query helpers! This means if you want to use tools like:

... and so on, you can! In your Encore service, use the new sqldb.Named function to get a database object, and then use its Stdlib method to get a *sql.DB object that you can integrate with any of these packages as you see fit.

package foo

// db is a *sql.DB that is automatically connected
// to the database belonging to the "foo" service.
//
// Like always with Encore, you don't need to worry
// about provisioning, database passwords, or having
// to set up schema migrations. It's all taken care of.
var db = sqldb.Named("foo").Stdlib()

Testing auth endpoints

If you're building an application with Encore's built-in authentication support, you're in luck! Testing endpoints that required authentication is now much easier than before, with the introduction of auth.WithContext:

import "encore.dev/beta/auth"

func TestAuthEndpoint(t *testing.T) {
    ctx = auth.WithContext(context.Background(), "some-user-id", &AuthData{})
    err := MyAuthEndpoint(ctx)
    // ...
}

//encore:api auth
func MyAuthEndpoint(ctx context.Context) error {
    // ....
}

This functionality is actually not limited to testing, and can be used anywhere, including in your business logic for cases where you need to make an API call on behalf of an authenticated user.

Bugfixes and other improvements

We also made lots of smaller improvements and bugfixes:

  • Added --port and --listen options to encore run to change listen port/address (#94)
  • Overhauled code generation for increased performance and maintainability
  • Fixed database request tracking in tests (#89)
  • Fixed a bug where the Dev Dashboard sometimes didn't show the latest result (#53)
  • Fixed return type mismatch between Encore runtime and client library (#55)
  • Fixed using unicode in API Explorer (#97)

We're looking forward to seeing what you build! Join us in Slack to participate in the growing community of Encore developers, and stay tuned for more updates soon!

Subscribe to our Engineering Blog

The latest ideas to help you build better software.

You can unsubscribe at any time.

© 2021 Encore. All rights reserved.