Google Cloud Endpoints Tips #6 : The @APIResourceProperty Annotation
December 2017: Please note that this post has not been updated for a while and there could be differences in terms of commands, screenshots and problems in running the code.
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 not appear in the result.
A sample listTask method invocation yields the following JSON response for the test data that I have in my system:
Hope this makes things clear. Go ahead and employ @APIResourceProperty !
List of Cloud Endpoints Tips
