Creating a Simple Hello World Backend API

In this part of the tutorial, we'll use the App Engine Maven artifact endpoints-skeleton-archetype to create a new Endpoints project that has the required directory structures and files. We'll then show you how to add code implementing a simple backend API.

Creating and building the project

To create the Hello World backend API:

1. In a terminal window, change to the directory where you want to build the project.

2. Invoke the following Maven command:

   mvn archetype:generate -Dappengine-version=1.9.9 -Dfilter=com.google.appengine.archetypes:
   

3. Supply the number corresponding to endpoints-skeleton-archetype from the list of App Engine archetypes.

4. Select the most recent version from the displayed list of available archetype versions by accepting the default.

5. When prompted to Define value for property 'groupId' , supply the namespace com.example . (The typical convention is to use a namespace starting with the reversed form of your domain name.)

6. When prompted to Define value for property 'artifactId' , supply the project name helloworld .

7. When prompted to Define value for property 'version' , accept the default value.

8. When prompted to Define value for property 'package' , accept the default value.

9. When prompted to confirm your choices, accept the default value ( Y ).

10. Wait for the project to finish generating, then take a look at the resulting project layout:

    

    The pom.xml file contains all the configuration and dependencies needed for your backend API. The file src/main/webapp/WEB-INF/web.xml maps the backend API servlet to the URL used to serve requests (no further configuration is required) and src/main/webapp/WEB-INF/appengine-web.xml is where you would specify the Google Developers Console project ID you obtained during Setup . We won't set this now, since we are not deploying, but if you wanted to deploy this app to that Google Developers Console project, you'd specify its project ID in the <application> setting in this file.

    In the Java source, the src/main/java/com/mycompany/helloworld/Constants.java file is where you'd put any client IDs for the project. We won't use these in this part of the tutorial, so ignore it for now. The src/main/java/com/mycompany/helloworld/YourFirstAPI.java file is where we'll add the API code. There is nothing magic about this name and you don't have to use it.

11. Change directories to the new project java source directory: helloworld/src/main/java/com/mycompany/helloworld .

12. Add a JavaBean class file named MyBean.java containing the following code:

    We'll use this JavaBean object to contain the data sent through the backend API. (In Endpoints, methods can only return Objects treated as JavaBeans or a collection of Objects which are converted to JSON to form the response.)

13. Edit the file YourFirstAPI.java , replacing all of the contents with the following code:

    Notice the annotation @Api ; this is where we set the configuration of the backend API. (See Endpoint Annotation for all of the available attributes of this annotation.) You always have to set the name and version.

Notice the @ApiMethod annotation; this isn't strictly needed here because all public methods within your API are automatically exposed. However, we show it because it is useful for specifying further configuration, such as if you wanted to use a different name for this method in the public API than the method name used in the actual implementation.

Finally, notice the use of the javax.inject.Named annotation ( @Named ) in the sayHi method definition. You must supply this annotation for all parameters passed to server-side methods, unless the parameter is an entity type .

1. Build the project by invoking

   mvn clean install
   

   Wait for the project to build. When the project successfully finishes you will see a message similar to this one:

   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 14.846s
   [INFO] Finished at: Tue Jun 03 09:43:09 PDT 2014
   [INFO] Final Memory: 24M/331M
   

Running and testing the API locally

To test the backend API locally:

1. From the main directory helloworld/ , start the API in the development server as follows:

   mvn appengine:devserver
   

   Wait for the dev server to start up. When it finishes starting up, you will see a message similar to this one:

   [INFO] INFO: Module instance default is running at http://localhost:8080/
   [INFO] Jun 03, 2014 9:44:47 AM com.google.appengine.tools.development.AbstractModule startup
   [INFO] INFO: The admin console is running at http://localhost:8080/_ah/admin
   [INFO] Jun 03, 2014 9:44:47 AM com.google.appengine.tools.development.DevAppServerImpl doStart
   [INFO] INFO: Dev App Server is now running
   

2. Visit the API Explorer at this URL:

   http://localhost:8080/_ah/api/explorer
   

   (The Google API Explorer is a built-in tool that lets you send requests to a backend service without using a client app.)

3. Click myApi API , which is your new backend API, to display the methods available from this API.

4. Click myApi.sayHi to display the Explorer form for this method:

   

5. In the name field, supply your name, and click Execute : check the Response for the greeting.

Congratulations!

You've just built and tested your first backend API!

Next, for a better understanding using a more fully featured backend API, lets create another backend, this time a complete backend API called Hello Endpoints , using a different Maven App Engine artifact.

Creating the HelloEndpoints Complete Sample Backend API >>

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .