Google Cloud Endpoints Tips #6 : The @APIResourceProperty Annotation

In this tip, we are going to discuss the @APIResourceProperty annotation, which is a very handy annotation that you could use for your API.

The documentation states “@ApiResourceProperty provides provides more control over how resource properties are exposed in the API. You can use it on a property getter or setter to omit the property from an API resource. You can also use it on the field itself, if the field is private, to expose it in the API. You can also use this annotation to change the name of a property in an API resource.”

I have intentionally highlighted some of the words in bold to make you focus on what this annotation can be used for. The first two points should be clear enough i.e. you can omit any property from appearing in the API response or to expose a private property.

The third one is something that I believe is very valuable and can make a big difference to your API. Changing the name of a property is useful in two specific cases (there might be others, so do chime in with your comments to augment my points!) :

  • Make the API Property more understandable
  • Reduce the length of the API property name to a short form. This is useful if you really care about the number of bytes in the response. For e.g. you might have an API Property name “AddressLine1″ and you might just want it to be “AL1″ and so on.

Let us understand it with an example:


@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class Task {

@PrimaryKey
@Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
@ApiResourceProperty(name="tid")
Long id;

@Persistent
@ApiResourceProperty(name="desc")
String description;

@Persistent
@ApiResourceProperty(ignored=AnnotationBoolean.TRUE)
String status;

// Getter / Setter methods
}

Note the following :

  • For the id property, we are using the @APIResourceProperty annotation and providing it a name =”tid”. This means that in the response the field label will be provided as tid.
  • For the description property, we are shortening the property name to desc.
  • For the status property, we are making the ignored attribute as TRUE, so that it does appear in the result.

A sample listTask method invocation yields the following JSON response for the test data that I have in my system:

gcep-apiresourceproperty

Hope this makes things clear. Go ahead and employ @APIResourceProperty !

List of Cloud Endpoints Tips 

  1. Check Endpoint Deployment Status
  2. Throw the Right Exception Classes
  3. Understand Injected Types
  4. Understand @API and @APIMethod Annotations
  5. Using Cursor and Limit parameters
  6. The @APIResourceProperty Annotation

Google Cloud Endpoints Tips #4 : Understand @API and @APIMethod Annotations

Google Cloud Endpoints provides convenient Annotations in Java to mark which of your classes is the API and which methods are exposed as the API Methods.

It does that via 2 convenient annotations: @API and @APIMethod.

The key points to remember for these annotations are as follows:

  • The @API annotations as per the documentation states “The annotation @Api is used to configure the whole API, and apply to all public methods of a class unless overridden by @APIMethod”. Note the words unless overridden. Often you find that you casually go ahead and mark a class with @API. The result is that all your public methods will be considered as possible candidates for methods of the API.
  • I recommend to use @API and @APIMethod together. Make sure that you mark only those methods that you want to expose as an API method with the @APIMethod annotation. This brings me to the next point that you should be aware of.
  • As per the documentation of @APIMethod, “all public, non static, non bridge methods in a class with an @Api annotation are exposed in the API, whether they have an @ApiMethod annotation or not”. Do make sure to revisit the various methods that you have in your class to avoid exposing them.

The above points are to do with design and it is not that you would not catch them, especially when you test them under the Local API Explorer, but it is important to help understand what goes on behind the scenes and what the tool does when generating the API Discovery Document and the Client Libraries.

List of Cloud Endpoints Tips 

  1. Check Endpoint Deployment Status
  2. Throw the Right Exception Classes
  3. Understand Injected Types
  4. Understand @API and @APIMethod Annotations
  5. Using Cursor and Limit parameters
  6. The @APIResourceProperty Annotation

Google Cloud Endpoints Tips #3 : Understand Injected Types

Typically, when you design your API and the associated methods, you do spend some time deciding what parameters will be passed for each API Method.

It pays to know about Injected Types, which are parameters that are given a special treatment by the Cloud Endpoints framework. These parameters when defined in the method signature will not need to be passed explicitly while making the call. Instead it will be the Cloud Endpoints framework that will populate it for you. You can then make sure of this inside of your method implementation.

As per the documentation, Cloud Endpoints supports the following 3 injected types:

  • com.google.appengine.api.users.User
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.ServletContext

The first one is used if you secure your API Endpoint. The User object will be passed to you. Always remember to check the user object for Null value and do your own validations as needed.

The next 2 injected types are very useful, especially if you wish to dig into the details of the HTTP Request , Servlet Context and do some investigation yourself. These two parameters come handy if your API method implementation is tightly coupled with the Web Framework. Maybe that is a hint to revisit your API :-)

List of Cloud Endpoints Tips 

  1. Check Endpoint Deployment Status
  2. Throw the Right Exception Classes
  3. Understand Injected Types
  4. Understand @API and @APIMethod Annotations
  5. Using Cursor and Limit parameters
  6. The @APIResourceProperty Annotation

Google Cloud Endpoints Tips #2 : Throw the Right Exception Classes

One of the hallmarks of a well-written API is to understand what it throws back to the clients when there is an exception.

For e.g. a REST API should make use of the correct HTTP Status Codes in its response. Some of the well-known status codes are 200 (OK) , 404 (Not Found), 500 (Internal Server Error) and so on. It is very important that you implement your Endpoint classes to throw back the correct status codes.

Cloud Endpoints does provide a mechanism for you to throw back Exception classes that will in return use the correct HTTP Status code in the response sent back to the client. As per the documentation, there are several exception classes made available in the com.google.api.server.spi.response package. Some of these exception classes are:

  • NotFoundException (HTTP 404)
  • UnauthorizedException (HTTP 401)

and so on. The usage is simple too. Here is a snippet for throwing a not found exception:

String message ="No entity exists with ID: "+ entityId;throw new NotFoundException(message);

The above would be the correct way to throw an exception. It is easy to make the mistake of throwing some other Java Exception (Persistence Layer), etc. This will result in a crazy response for the client with a trace, etc. So always catch the exceptions being thrown from the layers that Cloud Endpoints interacts with and then instantiate the correct exception.

Note that you can also create your own custom Exception classes that map to some other HTTP Codes. But do look out in the documentation for the status codes that you should not be overriding with your custom exception classes.

 

One of the areas where you will immediately notice the need for the correct exception classes is the default code that is generated for the endpoints from your Entity class. Look at the get and insert methods that it generates and you will find that it throws Entity Exceptions from the Persistence Layer. This is typically not a good idea and it is best to envelope this with the Exception classes that correctly map to the HTTP Codes.

Developers who are writing Client applications against your API and API tools will thank you.

List of Cloud Endpoints Tips 

  1. Check Endpoint Deployment Status
  2. Throw the Right Exception Classes
  3. Understand Injected Types
  4. Understand @API and @APIMethod Annotation
  5. Using Cursor and Limit parameters
  6. The @APIResourceProperty Annotation

Google Cloud Endpoints Tips #1: Check Endpoint Deployment Status

While deploying Cloud Endpoints to a live appspot.com domain, it is important to know if your endpoints deployed OK or not. The Logs Viewer of App Engine provides a good way for you to determine that.

Do the following:

  1. Deploy your App Engine project containing Cloud Endpoints.
  2. Once deployed successfully, go to the App Engine Administration Console and go to Logs Viewer.
  3. Scroll through the recent logs by time-stamp and you shall see something that looks like this:

Image

 

I have 5 Endpoints in my project and for each of the endpoints, it will provide a OK message as shown above.

The above quick tip is referenced from the documentation and it also mentions that in case there was a problem deploying the Endpoint, you should see an ERROR instead of OK.

List of Cloud Endpoints Tips 

  1. Check Endpoint Deployment Status
  2. Throw the Right Exception Classes
  3. Understand Injected Types
  4. Understand @API and @APIMethod Annotations
  5. Using Cursor and Limit parameters
  6. The @APIResourceProperty Annotation

App Engine Dev Tips #10 : Disable / Deleting an Application

You would tend to think that Deleting an Application should be a straight forward task via the Admin console but it is not and it shouldn’t be.

One thing to keep in mind before you delete the application: Are you really sure you want to delete the application? Assuming that you have made a conscious decision to delete it, be aware of the fact that once the application is deleted, you will not get back the Application ID. So if you had spent a good amount of time thinking about coming up with a nice and unique Application ID, keep in mind that its gone.

Now that we have got that point out of the way, let us go ahead with deleting the application:

  1. Login to App Engine (http://appengine.google.com) and click on the application that needs to be deleted.
  2. In the Admin Console, click on Administration -> Application Settings.
  3. In the right pane, you will see a Disable or Delete Application section as shown below:Screen Shot 2013-09-29 at 3.35.28 PM
  4. Click on the Disable Application button. This will bring up the screen shown below. If you want to temporarily stop your application, this is the best way to do it. Click on Disable Application Now. 
    Screen Shot 2013-09-29 at 3.37.32 PM
  5. Once you click on Disable Application Now, your application will stop serving requests. You will also be given confirmation of your action via the screenshot below:Screen Shot 2013-09-29 at 3.38.20 PM
  6. If you want to Re-enable it at any time, come back here and click on the Re-enable Application Now.
  7. But if you want to permanently delete the application, then click on the Request Permanent Deletion. Doing so, will mark your application for deletion. App Engine will actually delete your application only after 72 hours. You can revert back the request if you want. You will also get an email indicating that you have marked the application for deletion.Screen Shot 2013-09-29 at 3.37.56 PM
  8. This is a good step by App Engine because you don’t want to regret the deletion action that you have done in haste. Keep in mind that till the Application is actually deleted, the application (whether disabled or in the process of deletion) will still count towards your quota of number of applications (10). Once it is permanently deleted, only then a slot will free up.

Check out all the App Engine Development Tips.

App Engine Dev Tips #9 : App Engine Services Configuration

App Engine provides applications with various services like XMPP and Mail Service. To use these services, you would typically understand the API and use that in your application.

When you deploy your App Engine application that utilises any of these services, you must configure them in the war/WEB-INF/appengine-web.xml file. This is the same file in which you will find your application ID, version and other configuration data.

An example of configuring XMPP and Mail Service is shown below:

<inbound-services>
  <service>mail</service>
  <service>xmpp_message</service>
</inbound-services>

Often, one forgets including these services or does not configure them correctly and then we end up spending precious time on why the service was not working in the actual instance. One tip is that whenever you update any services in the appengine-web.xml, please ensure that after deployment, these services were indeed made available and configured for your application.

To do that, after deployment, visit the Admin console and visit Administration -> Application Settings. 

Scroll down on the right pane and you will see a list of available services for your application. Ensure that the ones that you did setup in the appengine-web.xml are present.

Check out all the App Engine Development Tips.