Go, Cloud Endpoints and App Engine
Part 3
Before we can start work on Part 3 of this tutorial, we will need to cover a lot of ground in terms of understanding Go’s templates, forms, and App Engine’s datastore.
TIP: If you are new to Go, you need to read and run the examples in the following articles first:
I have made extensive references to the following articles.
Thanks to:
- Google’s Go Tutorial for its App Engine.
- Romin Irani’s idea of generating a Quotes API. Our goal is going to be to write a public API that will allow us to manage Famous Quotes. A Quote is a famous or a philosophical statement said by an eminent person.
- go-endpoints — Package “endpoints” will let you write Cloud Endpoints backend in Go.
- Polymer Gopher by Francesc Campoy.
We noted in Part 1 that Google Cloud Endpoints is a solution from Google, consisting of tools, libraries and capabilities that allow you to generate APIs and client libraries from a Google App Engine application, referred to as an API backend (i.e. it helps you create a Public API for your App Engine application), to simplify client access to data from other applications.
Also, our goal is going to be to write a public API that will allow us to manage Famous Quotes. A Quote is a famous/philosophical statement said by an eminent person.
Install Cloud Endpoints for Go
Refer the documentation for Cloud Endpoints for Go. This package will let you write Cloud Endpoints backends in Go.
Use the goapp tool from the Go App Engine SDK to get the package:
c:\go_appengine>goapp get github.com/GoogleCloudPlatform/go-endpoints/endpointsTip: If you have already installed endpoints earlier, it makes sense to update the same. Add “-u” param to get an updated version, i.e.
go get -u github.com/GoogleCloudPlatform/go-endpoints/endpointsThe documentation says:
Now, you’ll see a couple errors, which is OK, don’t worry!
package endpoints usage
import “github.com/GoogleCloudPlatform/go-endpoints/endpoints”Package “endpoints” will let you write Cloud Endpoints backend in Go.
Declare structs which describe your data
Go Endpoints has its own field tag “endpoints” which you can use to let your clients know what a service method data constraints are (on input):
- “req”, means “required”. Validation will fail if the value equals the zero value of the type.
- “d”, default value, cannot be used together with “req”.
Service
We will have a “quotesService” and at this point have two methods i.e. “Add” and “List”.
Add method
Datastore entities are the unit of storage and are associated with a key.
We set the same parent key on every Quote entity to ensure each Quote is in the same entity group. Queries across the single entity group will be consistent. Putting an entity into the datastore under a new incomplete key will cause a unique key to be generated for that entity.
List method
“List” returns a list of all the existing quotes.
Register the QuotesAPI with cloud endpoints
Let’s make the above two services available as a discoverable API and leverage all the juicy stuff Cloud Endpoints are great at.
In the “init()” method we shall register the “QuotesAPI” with cloud endpoints as follows:
Read the RegisterService documentation.
“RegisterService” adds a new service to the server where name is “quotesService”, version is “v1”, description is “Quotes API” and the default value is true.
Register the List and Add methods
info := api.MethodByName(“List”).Info()MethodByName returns a ServiceMethod of a registered service’s method or nil. RpcService represents a service registered with a specific Server. Info returns a ServiceInfo which is used to construct Endpoints API config.
Start handling cloud endpoint requests
endpoints.HandleHTTP()Here’s the documentation for HandleHTTP.
goendpoint.go — the complete program
This file is stored in the folder: “$GOPATH/src/github.com/SatishTalim/quotesnew”
The app.yaml file
This file is stored in the folder: “$GOPATH/src/github.com/SatishTalim/quotesnew”
It is now time to start the development web server and use the API Explorer.
From the “$GOPATH/src/github.com/SatishTalim” directory run the following command, to compile your app and start the development web server:
goapp serve quotesnew/The web server is now running, listening for requests on port 8080.
In your browser use the API Explorer with the URL:
http://localhost:8080/_ah/api/explorerYou should see a screen like this:
Click the shield in the URL bar and click on “Load unsafe scripts”.
After some time, you should see next to “Services” “quotesservice API”.
Click on “quotesservice API” and you should see “quotes.addQuote” and “quotes.getQuotes”.
Next, click on “quotes.addQuote” and a screen as shown below pops up:
Click on “Use fields editor” and select “author” and “message” on the screen that comes up and click on “Close”.
Next, click on “Request body” field and select “add a property” “Author” and enter your author’s name say “Romin”. Next, “add a property” “Message” and enter the quote say “Yes. We can!” Click on the “Execute” button twice. Congrats! A quote has been created.
Finally, click on “quotesservice API” and select “quotes.getQuotes”. Click on “Use fields editor” and click on “Select all/none” and click on the “Close” button. Next click on the “Execute” button. You should see the quote that you had just entered as shown below:
You can now deploy the app to appspot.com say http://myapp.appspot.com. Use the explorer to add and list quotes.
Exercise: As an exercise implement the “Update” and “Delete” methods for this service. Refer to the official Go Datastore API.
Extra: You can refer here to generate Client libraries that can interact with your API.
For the JavaScript API, the recommended way is to use the Google JS API. A Javascript tutorial explains building a web (JavaScript) client that uses the API.
A note by Romin Irani:
You will need to use either core JavaScript $.ajax calls to hit the Endpoints with GET, PUT, POST, DELETE methods or use a 3rd party JavaScript library like jQuery / REST libraries to work with the endpoints that we have exposed. If you do not want to use the standard Google JS client API, you can still hit the endpoints on your own.
If anyone does write a simple client not using the Google JS client API, do let me know.
Note: I would love your feedback on these study notes. If I can make it better, I’d love it!
