Up until now, you just learned how to execute methods when a new object is created,read, updated or deleted. But let's suppose you want to implement methods that are executed whenever you want it, and not just when a CRUD-Method is executed. As this is just an introduction, more details about the usage and implementation of the module can be found here.

Let's for example say that your grocery list has gotten really big and you're not sure anymore if you can even afford all of it. So you want to implement a method that calculates the overall pricing of all the groceries, and depending on the money you have returns if you can afford it or not.

But first, let's have a look at a very easy example that is already provided in every downloaded module: the ping-rest-endpoint.

The Ping Example

Inside the project with your downloaded module-code, go to the class com.apiomat.nativemodule.[modulename].[modulename] (just as at the start of the config-parameter-tutorial)
Search for the method getSpecificRestResource . This method signalizes if the module provides own restentpoints at all. This "switch" is turned of by default. Turn it commenting the "return null" and uncommenting the line "return new RestClass(.....".
Upload the module-code as always
Gow to the Dashboard. Now you can access a new rest-method. This restmethod was implemented as a default all along, it just was not activated up until now. There are vairous ways in which you can access rest-endpoints of a module. the most easy one is to go to "My Modules > Native Modules" and search for the entry for your module. You have been here before in this turorial to download your module code the first time! But now, there is a new area providing REST endpoints for this module. There is just one method available, the "A simple ping-like GET endpoint"-method. Enter the parameters, which is a name of your choice and the name of the application, hit the execution button and check the response: It's the name you entered. A simple ping .
There is a second way to execute this rest-endpoint, which is directly accessing the URL where the resource resides. In the case of own rest-endpoints, thes are located: " [base-url-of-server]/yambas/rest/modules/[moduleName]/[appName]/spec/ping/[wordYouWantThePingToReturn] ". In this example, this equals: " [base-url-of-server]/yambas/rest/modules/TutorialModule/TutorialApp/spec/ping/helloRest . You should see the last word entered into the URL.

Now you should have a vague idea of how to use a rest-endpoint. The question is, where did this ping-method come from in the first place?

Return to the project with the module-code you once downloaded. go to the class com.apiomat.nativemodule.[modulename].RestClass
1. This class contains all the rest-methods of this module. At the bottom there is the source-code for the ping-method you just used. The code-below explains the meaning of the different parts of this method through comments.
  
  @ApiOperation(
  
  value = "A simple ping-like GET endpoint", // The text on the button of the method you saw in the dashboard
  
  position = 1 ) // Indicates the order of your rest-methods if you have more than one
  
  @GET // Indicates the type of the rest method (GET, POST, PUT, DELETE)
  
  @Path( "/ping/{param}" ) // Indicates the path to this method when calling it directly through the
  
  // through the URL. Check the url you typed in again.
  
  // You should see the resemblance
  
  public Response ping( @ApiParam( value = "param name" ) @PathParam( "param" ) String param ) // The actual signature of the method.
  
  // The @ApiParam( value = "param name") indicates the name of this parameter
  
  // you saw when accessing the method through the dashboard.
  
  // The @PathParam( "param" ) String param - part indicates the name of the param
  
  // you can use inside your method...
  
  {
  
  final com.apiomat.nativemodule.Request request = this.getAOMRequest( ); // This call provides you with the incoming request,
  
  // in case you need it
  
  System.out.println( request );
  
  return Response.ok( param ).type( MediaType.TEXT_PLAIN ).build( ); // the return-statement. As you can see, the incoming param
  
  // is returned and some obligatory formatting applied.
  
  }

Got it? Let's write our own rest-method!

Writing an own Rest-Endpoint

Let's remember what we actually tried to achive: The Rest-Endpoint should recive your money as input, caluclate the overall pricing of all the groceries currently in the database, and then tell you if you do or don't have enough money. Its' recommended to copy the ping-method as a bluepring and alter it. Here you can see the solution:

@ApiOperation(
        value = "Can I go shopping with this money?",
        position = 1 )
    @GET
    @Path( "/canIAffordIt/{theMoney}" )
    public Response canIAffordIt( @ApiParam( value = "your money" ) @PathParam( "theMoney" ) String yourMoney )
    {
        final com.apiomat.nativemodule.Request r = this.getAOMRequest( );
 
        IModel<?>[ ] groceriesInDatabase =
            TutorialModule.AOM.findByNames( r.getApplicationName( ), Grocery.MODULE_NAME, Grocery.MODEL_NAME, "", r );
        double sum = 0;
 
        for ( IModel<?> grocery : groceriesInDatabase )
        {
            Grocery g = ( Grocery ) grocery;
            sum += g.getPrice( );
        }
 
        TutorialModule.AOM.log( r.getApplicationName( ), "Current value of all groceries: " + sum );
 
        Double money = Double.parseDouble( yourMoney );
        if ( sum < money )
        {
            return Response.ok( "you have enough money !" ).type( MediaType.TEXT_PLAIN ).build( );
        }
 
        return Response.ok( "you don't have enough money !" ).type( MediaType.TEXT_PLAIN ).build( );
    }

Most of this should be self-explanatory following the ping-example. Some additional Informations:

IModel<?>[ ] groceriesInDatabase = TutorialModule.AOM.findByNames( r.getApplicationName( ), Grocery.MODULE_NAME, Grocery.MODEL_NAME, "", r );
- This mehtod queries and retrives all instances of a given class-name (aka "module-name"). This means that this method retrives all groceries currently saved in the database. The other parameters of this method, like the application-name and so on are for the apiomat to localize the class you are trying to access.
- The empty parameter of this call [ "" ] recives a query. If you wrote something like "price > 3". You already came briefly in touch with queries for databases in this tutorial. Ase we passed an empty query, simply all instances are returned. For further explanations concerning queries, look here.
- This method always returns the an array of all queried instances as the type "IModel<?>", which is the global parent-class from which all models of the apiomat inherit from.
```
Grocery g = ( Grocery ) grocery
```
- The instances return by the previous call currently have the type "IModel<?>", which is the global parent-class from which all models of the apiomat inherit from. You have to type-cast them to the actual type.

Now you can upload the module code again, go to the dashboard, browse through "my-modules" and search for your module. The new method should be there and work as intented! Also try to access this method through the URL-Method we tried out for the ping-example.

images/download/attachments/12651048/checkYourNewRestEndpoint.png

You just saw two methods to access your own Rest-Endpoint. Acutally, there is a third one, explained in the next tutorial.

Own Restendpoints

The Ping Example

Writing an own Rest-Endpoint

Search results