Google Cloud Endpoints Tips #4 : Understand @API and @APIMethod Annotations
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.
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