Building Microservices in Go
- Designing Services API First
- Scaffolding a Microservice
- Building Services Test First
- Deploying and Running in the Cloud
- Summary
Learn to build a service by following the practice of API First, designing your service’s RESTful contract before you write a single line of code. Then, when it does come time to write code, start by writing tests first. By writing small tests that go from failure to passing, you will gradually build out your service.
This chapter is from the book
This chapter is from the book
This chapter is from the book
“The golden rule: can you make a change to a service and deploy it by itself without changing anything else?”
Sam Newman, Building Microservices
Every service you build should be a microservice, and, as we’ve discussed earlier in the book, we generally disagree with using the prefix micro at all. In this chapter we’re going to be building a service, but this chapter is as much about the process as it is about the end result.
We’ll start by following the practice of API First, designing our service’s RESTful contract before we write a single line of code. Then, when it does come time to write code, we’re going to start by writing tests first. By writing small tests that go from failure to passing, we will gradually build out our service.
The sample service we’re going to build in this chapter is a server implementation of the game of Go. This service will be designed to enable clients of any kind to participate in matches of Go, from iPhones to browsers to other services.
Most importantly, this service needs a name. A service written in Go that resolves matches of the game of Go can be called nothing less than GoGo.
In this chapter, we’re going to cover:
API First development disciplines and practices.
Creating the scaffolding for a microservice.
Adding tests to a scaffolded service and iterating through adding code to make tests pass.
Deploying and running a microservice in the cloud.
Designing Services API First
In this next section we’re going to design our microservice. One of the classic problems of software development is that what you design is rarely ever what you end up developing. There is always a gap between documentation, requirements, and implementation.
Thankfully, as you’ll see, there are some tools available to use for microservice development that actually allow a situation where the design is the documentation, which can then be integrated into the development process.
Designing the Matches API
The first thing that we’re going to need if we’re creating a service that hosts matches is a resource collection for matches. With this collection, we should be able to create a new match as well as list all of the matches currently being managed by the server shown in Table 5.1.
Table 5.1 The Matches API
Resource |
Method |
Description |
/matches |
GET |
Queries a list of all available matches. |
/matches |
POST |
Creates and starts a new match. |
/matches/{id} |
GET |
Queries the details for an individual match. |
If we were building a game of Go that we were hoping to sell for real money, rather than as a sample, we would also implement methods to allow a UI to query things like chains and liberties, concepts essential to determining legal moves in Go.
Designing the Moves API
Once the service is set up to handle matches, we need to expose an API to let players make moves. This adds the following HTTP methods to the moves sub-resource as shown in Table 5.2.
Table 5.2 The Moves API
Resource |
Method |
Description |
/matches/{id}/moves |
GET |
Returns a time-ordered list of all moves taken during the match. |
/matches/{id}/moves |
POST |
Make a move. A move without a position is a pass. |
Creating an API Blueprint
In our desire to simplify everything we do, some time ago we started to eschew complex or cumbersome forms of documentation. Do we really need to share monstrous document files that carry with them decades of backwards compatibility requirements?
For us, Markdown1 is the preferred form of creating documentation and doing countless other things. It is a simple, plain text format that requires no IDE or bloated editing tool, and it can be converted and processed into countless formats from PDF to web sites. As with so many things, the debate over which format people use for documentation has been known to spark massive, blood-soaked inter-office battles.
As a matter of habit, we typically create Markdown documents that we bundle along with our services. This allows other developers to quickly get a list of all of our service’s REST resources, the URI patterns, and request/response payloads. As simple as our Go code is, we still wanted a way to document the service contract without making someone go sifting through our router code.
As it turns out, there is a dialect of Markdown used specifically for documenting RESTful APIs: API Blueprint. You can get started reading up on this format at the API Blueprint website https://apiblueprint.org/.
If you check out the GitHub repository for this chapter (https://github.com/cloudnativego/gogo-service), you’ll see a file called apiary.apib. This file consists of Markdown that represents the documentation and specification of the RESTful contract supported by the GoGo service.
Listing 5.1 below shows a sample of the Markdown content. You can see how it describes REST resources, HTTP methods, and JSON payloads.
Listing 5.1 Sample Blueprint Markdown
### Start a New Match [POST]
You can create a new match with this action. It takes information about the players
and will set up a new game. The game will start at round 1, and it will be
**black**'s turn to play. Per standard Go rules, **black** plays first.
+ Request (application/json)
{
"gridsize" : 19,
"players" : [
{
"color" : "white",
"name" : "bob"
},
{
"color" : "black",
"name" : "alfred"
}
]
}
+ Response 201 (application/json)
+ Headers
Location: /matches/5a003b78-409e-4452-b456-a6f0dcee05bd
+ Body
{
"id" : "5a003b78-409e-4452-b456-a6f0dcee05bd",
"started_at": "2015-08-05T08:40:51.620Z",
"gridsize" : 19,
"turn" : 0,
"players" : [
{
"color" : "white",
"name" : "bob",
"score" : 10
},
{
"color" : "black",
"name" : "alfred",
"score" : 22
}
]
}
Testing and Publishing Documentation with Apiary
In Chapter 1, The Way of the Cloud, we cautioned against relying too heavily on tools. Tools should make your life easier, but they should never be mandatory. The API Blueprint Markdown that contains the documentation and specification for our service is just a simple text file, however, there is a tool that can do a lot to make our lives both easier and more productive.
Apiary is a website that lets you interactively design your RESTful API. You can think of it as a WYSIWYG editor for API Blueprint Markdown syntax, but that’s just the beginning. Apiary will also set up mock server endpoints for you that return sample JSON payloads. This saves you the trouble of having to build your own mock server, and lets you remain in API First mode until after you’ve gone through the motions of exercising various rough drafts of your API.
In addition to exposing mock server endpoints, you can also see client code in a multitude of languages that exercises your API, further assisting you and your team in validating your API—all before you have to write a single line of server code.
The API Blueprint document for the GoGo service is available in our GitHub repository as well as on Apiary for viewing at http://docs.gogame.apiary.io/. Rather than dump the entire set of documentation into the book, we’ll leave most of the details in the blueprint document and on Apiary for you to read on your own.
The purpose of this chapter isn’t to teach you how to make a game server, but to teach you the process of building a service in the Go language, so details like the rules of Go and actual game implementation will be secondary to things like Test-Driven Development and setting up a service scaffold, which we’ll cover next.