Own REST interfaces
A class RestClass is generated in every Native Module SDK automatically. It inherits from AbstractRestResource and is meant to contain the logic which will be triggered by REST calls. If you prefer to use another class or want to use several classes or a complex class hierarchy for custom REST interfaces, you can create additional classes that behave in the same way - they just have to implement AbstractRestResource.
public class RestClass extends AbstractRestResource{ public RestClass( UriInfo uriInfo, HttpServletRequest servletRequest, SecurityContext securityContext, Request wsRequest ) { super( uriInfo, servletRequest, securityContext, wsRequest ); } ...}
The hook method getSpecificRestResource(...) is generated into the module's main class, which name equals the module's name. By default the method returns null. If you want to use the above mentioned class(es), you have to return an instance of the class:
public AbstractRestResource getSpecificRestResource( UriInfo uriInfo, HttpServletRequest servletRequest, SecurityContext securityContext, Request wsRequest ){ return new RestClass( uriInfo, servletRequest, securityContext, wsRequest );}
An example for a custom REST interface is contained in the RestClass (method ping(...)).
Now any number of REST endpoints can be created in the REST class using the Jersey library (currently version 1.16). Find out more about this in the Jersey docs: https://jersey.java.net/documentation/1.16/jax-rs.html.
The REST service will be available under
{BASEURL}/yambas/rest/modules/{MODULNAME}/{APPNAME}/spec/
after re-uploading the module.
The relations between the classes are as follows:
|
image/svg+xmlIModuleMyModuleRestClassAbstractRestResourcegetSpecificRestResource(...) |
Authentication and Authorization
Helper methods provide several possibilities to check auth programmatically. See more at the
separate article
. Link
API documentation of your own REST endpoints
You can also create an API documentation of your own custom REST endpoints that gets shown in the "My Modules / Native Modules" page in the Dashboard as well as in the Apidocs.
To do that, you need to add Swagger annotations to your REST method. The following example shows an annotation of an example REST endpoint that's contained (but not used) in every Native Module:
/** * A simple ping-like GET endpoint. * You can pass a <PARAM> to the following URL, which is contained in the response then. * * curl <BASEURL>/yambas/rest/modules/Gille/spec/ping/<PARAM> * * The @ApiOperation and @ApiParam annotations are used to documnt the REST endpoint in the apidocs: * <BASEURL>/apidocs/index.html * * @param param arbitrary value which is returned in response * @return response */ @ApiOperation(value = "A simple ping-like GET endpoint" ) @GET @Path( "/ping/{param}" ) public Response ping( @ApiParam( value = "param name" ) @PathParam( "param" ) String param ) { final com.apiomat.nativemodule.Request request = this.getAOMRequest( ); // extract auth information from the request object if needed System.out.println( request ); return Response.ok( param ).type( MediaType.TEXT_PLAIN ).build( ); }Please note: To enable the documentation, the module needs to be "released". Be aware that after releasing the module, it's usable as library in other modules and it's available to other customers on the module market.
Version changes
Since Swagger changed its format and package structure, you have to ensure that you are using the annotations of Swagger >= 1.5 starting with ApiOmat 2.4.0. The new packages are starting with io.swagger instead of com.wordnik. You have to update your module's REST class(es) with the new package - Otherwise it won't be shown in the Apidocs furthermore.