RESTful API support
July 09, 2021
2 Min Read

Encore now has support for defining RESTful APIs in an easy, powerful way!

API Paths

Defining APIs can now include the path=/foo/bar and method=FOO parameters to customize the HTTP path and method the API is exposed at:

type CreateOrderParams struct { /* ... */ }
type Order struct { /* ... */ }    

//encore:api public path=/orders method=POST
func CreateOrder(ctx context.Context, p *CreateOrderParams) (*Order, error) { /* ... */ }

Path parameters

You can also define custom API path parameters such as path=/orders/:id.

When you specify a parameter, Encore passes that parameter directly to your function as a separate argument, like so:

type Order struct { /* ... */ }    

//encore:api public path=/orders/:id method=GET
func GetOrder(ctx context.Context, id int) (*Order, error) { /* ... */ }

Encore automatically performs validation of the parameter, according to the type used in the function signature. In this case id must be an integer. You can also use string, bool, uint8, and so on. You can even use encore.dev/types/uuid.UUID if you want to receive UUIDs.

Conflicting paths

Encore parses all the APIs in your application and ensures they don't conflict. For any given API call there can only ever be zero or one API that matches. If you define paths that conflict, Encore raises a compilation error.

Making API calls between services

Like always, Encore makes it easy to do API calls between services, and these parameterized APIs work just as easily as before: just call the function: service.GetOrder(ctx, 5).

Secrets Management

Encore's web platform now provides much-improved secrets management support. You can view, update, and roll back secrets to previous versions.

Contributions

  • Many thanks to @Willyham for initiating the custom API path support and implementing a large part of it!