Go, Cloud Endpoints and App Engine
Part 2
In Part 1 we talked about APIs, Google Cloud Endpoints, and Google App Engine.
Preamble: Since this article is for developers new to Go, the following two articles would be useful:
Download and Install the App Engine SDK for Go
To start developing Google App Engine applications in Go, you first download (for your operating system) and set up the App Engine Go software development kit (SDK).
Next follow the instructions on the download page to install the Go App Engine SDK on your computer. I installed the Go App Engine SDK to “C:\go_appengine” on my Windows 7 desktop.
The Go App Engine SDK will run on any Intel-based Mac OS X, Linux or Windows computer with Python 2.7. If necessary, download and install Python 2.7 for your platform from the Python web site. Most Mac OS X users already have Python 2.7 installed. If you have issues with the Python tools, please ensure you have Python 2.7 installed.
The Go App Engine SDK includes a web server application that simulates the App Engine environment, including a local version of the datastore, Google Accounts, and the ability to fetch URLs and send email directly from your computer using the App Engine APIs.
Later on we will use the following two commands from the Go App Engine SDK:
- goapp serve — for running a local development server
- goapp deploy — for uploading your app to the App Engine
You can find these commands in the “C:\go_appengine” directory. To simplify development and deployment, consider adding this directory to your PATH environment variable.
Tip: While setting the PATH ensure that “C:\go_appengine” comes after “C:\go\bin” i.e. it should be like PATH=C:\go\bin;C:\go_appengine;… This ensures that we use the ‘go’ command from the original Go installation and not the ‘go’ command from the Go App Engine.
Let us build a small app (mytext.go) locally
The local development environment lets you develop and test complete Go App Engine applications before showing them to the world. Let us write some code.
Go App Engine applications communicate with the outside world via a web server compatible with Go’s http package. This makes writing Go App Engine applications very similar to writing stand-alone Go web applications.
Let us begin by implementing a tiny application that displays a short message to a user.
Program mytext.go
Inside a folder “$GOPATH/src/github.com/SatishTalim” create the folder “mytext”. Replace “SatishTalim” with your GitHub id.
Next inside the “mytext” folder, create a file named “mytext.go”, and give it the following contents:
This Go package responds to any request by sending a response containing the message: “Hello. This is our first Go web app for the Google App Engine!”
Note:
- when writing a stand-alone Go program we would place this code in package “main”. The Go App Engine Runtime provides a special “main” package, so you should put HTTP handler code in a package of your choice (in this case, “mytext”).
- to work with some printing functions, we import the package fmt.
- the App Engine Go API uses the standard http package as an interface between your Go program and the App Engine servers. Thus for web related http functionality, we import the package http. Any functions within that we refer as “http.function_name”.
- within the “init” function, we redirect any incoming requests to the handler function. We do this by calling http.HandleFunc and passing it two parameters — the first one is a part of the incoming URL, and the second is the method capable of handling it.
- the function handler takes an “http.ResponseWriter” and an “http.Request” as its arguments.
- when a user connects, the program responds with a text that is sent back to the browser. The “http.ResponseWriter” value assembles the HTTP server’s response; by writing to it, we send data to the HTTP client.
- an “http.Request” is a data structure that represents the client HTTP request.
- all the parameters of a request can be received via the parameter “http.Request” in the handler. You can get the URL, the input values, and other details.
Create the Configuration File
An App Engine application has a configuration file called “app.yaml”. Among other things, this file tells the App Engine service which runtime to use and which URLs should be handled by our Go program.
Inside the “$GOPATH/src/github.com/SatishTalim/mytext” directory, create a file named “app.yaml” with the following contents:
From top to bottom, this configuration file says the following about this application:
- The application identifier is “helloworld”. When you register your application with App Engine later on, you will select a unique identifier, and update this value (later on we will update this value). This value can be anything during development. For now, leave it set to “helloworld”.
- This is version number 1–0 of this application’s code. Your application versioning information can contain alphanumeric characters and hyphens. If you adjust this before uploading new versions of your application software, App Engine will retain previous versions, and let you roll back to a previous version using the administrative console.
- This code runs in the go runtime environment, with API version “go1”.
- Every request to a URL whose path matches the regular expression /.* (all URLs) should be handled by the Go program. The “_go_app” value is a magic string recognized by the development web server; it is ignored by the production App Engine servers.
All Go packages for a given app are built into a single executable, and request dispatch is handled by the Go program itself. This is why we call “http.HandleFunc” inside the “init” function to associate our handler with the web root (“/”). However, you may still use the “app.yaml” file to configure paths that serve static files or require special permissions.
For a complete list of configuration options, see the Go Application Configuration page.
Test the App
You can now test your app with the web server included with the Go App Engine SDK. The application’s directory should contain the files “mytext.go” and “app.yaml”.
From the “$GOPATH/src/github.com/SatishTalim” directory run the following command, to compile your app and start the development web server:
goapp serve mytext/The web server is now running, listening for requests on port 8080. Test the application by visiting the following URL in your web browser: http://localhost:8080/. For more information about running the development web server, including how to change which port it uses, see the Development Server reference.
Iterative Development
The development app server knows to watch for changes in your file. As you update your source, it recompiles them and relaunches your local app. There’s no need to restart “goapp serve”.
Try it now:
- leave the web server running, then edit “mytext.go” to change “Hello. This is our first Go web app for the Google App Engine!” to something else. Reload http://localhost:8080/ to see the change.
- leave the web server running, then edit “mytext.go” to change “fmt.Fprint” to just “Fprint”. Observe the error in the console. Now change “Fprint” back to “fmt.Fprint” and observe the console.
To shut down the web server, make sure the terminal window is active, then press Control-C (or the appropriate “break” key for your console).
You now have a complete Go App Engine application! You could deploy this simple program right now and share it with users worldwide.
Uploading Your App to Google’s App Engine
Registering the App
You will now need to have a Google account. If you do not have a Google account, you can create a Google account with an email address and password.
You create and manage Go App Engine applications from the Developers Console at this URL.
To create a new application, click the “Create a Project” button. A screen pops up as shown below:
Enter “gochgmsg” for the Project name. It creates a unique project ID which in our case is “gochgmsg-1057”.
We have elected to use the free “appspot.com” domain name. With that, the full URL for the application will be http://gochgmsg-1057.appspot.com/.
Edit the “app.yaml” file, then change the value of the application: setting from “helloworld” to “gochgmsg-1057”.
Upload and Access the app
To upload your app, from the folder: “$GOPATH/src/github.com/SatishTalim” type:
goapp deploy mytext/If you see compilation errors, fix the source and rerun “goapp deploy”; it won’t launch (or update) your app until compilation is successful.
Romin Irani says: One issue that users could face while deploying the app — if you have multiple Google Accounts and the default one in which you are logged in currently is not the one that is containing the App Engine project, then the “goapp deploy” will fail with the error “The application does not exist ..<appid>”, etc. Unfortunately, the only recourse then is that the default account is the one owning the App Engine app or you have to use the “appcfg.py” command to set the no_cookies, etc. and do the deploy again.
Accessing Your Application
You can now see your application running on App Engine. We have our message app running, that you can access and check out.
Congrats! You have just successfully launched your first Go web app on the Google App Engine for the world to see!!
Note: I would love your feedback on these study notes. If I can make it better, I’d love it!
In Part 3 we write a program using Google Endpoints.
