Product Updates

The REST Template Project

Tristan Cartledge

August 2, 2022

Github Repository: speakeasy-api/rest-template-go (opens in a new tab)

Building a RESTful API can be daunting for developers who have never done it before (and even those who have). There are a number of choices and best practices that need to be considered as part of an API’s implementation; it can be hard to know where to start. That’s why we’re pleased to announce the RESTful API template project. (opens in a new tab) Over the coming months, we will release RESTful API templates for the most used programming languages – starting today with Go (opens in a new tab).

This is the template that our team forks from when we are building new APIs. The repo contains a CRUD API for a ‘user’ resource which incorporates the best practices needed for a basic REST service. Our hope is that developers can use this as a foundation upon which to build their own sets of APIs.

The service represents our team’s opinionated stance about what makes for good RESTful API code. Specifically, the template gives you a service which is:

• Entity-based: The resources available should represent the domain model. Each resource should have the CRUD methods implemented (even if not all are available to API consumers). In our template, we have a single resource defined (users.go). However other resources could be easily added by copying the template and changing the logic of the service layer.
• Properly Abstracted: The transport, service, and data layers are all cleanly abstracted from one another. This makes it easy to apply updates to your API endpoints.
• Consistent: It’s important that consumers of a service have guaranteed consistency across the entire range of API endpoints and methods. In this service, responses are consistently formatted whether successfully returning a JSON object or responding with an error code. All the service’s methods use shared response (http.go) and error (errors.go) handler functions to ensure consistency.
• Tested: We believe that a blend of unit and integration testing is important for ensuring that the service maintains its contract with consumers. The service repo therefore contains a collection of unit and integration tests for the various layers of the service.
• Explorable: It is important for developers to be able to play with an endpoint in order to understand it. We have provided Postman collections for testing out the REST endpoints exposed by the service. There is a Bootstrap Users collection that can be run using the Run collection tool in Postman that will create 100 users to test the search endpoint with.

We look forward to hearing from the community what they think of the repo. We’d love to know what else people would want to see included in a template: versioning, pagination, authentication?  Would people want to see more advanced features?