Getting Started: Learn

As part of the Akula installation, a sample HelloWorld app is included which provides a server baseline to quickly get up and running.  The goal of this knowledge path is to take the HelloWorld starter app and, after following these steps, have a fully functioning Akula Server that integrates with local RESTful services and be able to interact with it using an iOS, Android, or JavaScript client embedded with Akula libraries.  To accomplish this, we will uplift the HelloWorld app to a more complete app called ToDo.

By the time you are done with these steps, you will have performed the following:

  • Integrated the Akula Server with a data source
  • Configured authentication and authorization on the Akula Server
  • Implemented an Akula Server app property
  • Built and deployed an Akula app scope
  • Interacted using a client with Akula libraries

Before beginning this exercise, please download the supporting files.
 

HelloWorld Sample App Scope

As part of the Akula installer, a sample HelloWorld app scope is included. Instructions for running the HelloWorld app scope from a command line or from an IDE as a Maven project should be followed and can be found at Server Hello World Sample App.

Deploy the Data Source

The Akula automated installer installs a local Apache Tomcat server.  For more information about configuring and managing your local Tomcat instance, please reference our server installation documentation here: 3. Install the Akula Server on Your Java Server

As part of this exercise, you will integrate the Akula Server with a sample RESTful data source included in the supporting files. As you dig deeper with Akula, you can replace this sample data source with your own backend.

Deploy the /ToDoSupportingFiles/todo-rest.war file to the webapps directory of your Tomcat server, or to the JBOSS_HOME/standalone/deployments directory for JBoss (you may have to restart your Java server).

This creates the backend data source (i.e. RESTful service) which Akula consumes. To confirm you deployed it correctly, browse to the following URL: http://[domain]:[port]/todo-rest.  In this example, we will use localhost as the domain and 8080 as the port so the URL will look like: http://localhost:8080/todo-rest.

If you have any trouble, further documentation on this setup can be found here: Configuring your local environment for the ToDo app.

No action is required, but to explore the data source further, the REST service API can be found here: todo-rest.war REST Endpoints.

Build the ToDo App

Now that you have the the HelloWorld sample app scope running successfully and deployed the ToDo RESTful service, let’s walk through the steps needed to uplift the HelloWorld sample app scope into the fully functional ToDo app:

  1. In your IDE's local workspace, copy the HelloWorld project and rename it to ToDo to allow for both projects to run side-by-side.  To do this, either copy/paste the project's directory in your file system or copy the project in the IDE.  An instructional video on how to import an Akula app into an IDE can be found at Working With Akula Services Within Your IDE.

  2. In the pom.xml file for the ToDo project, make the following updates:

    ElementFromTo
    <name>helloworldToDo
    <artifactId>helloworldToDo
    <description>Akula Hello World AppAkula ToDo App

    Build and deploy the ToDo app scope from a command line or from an IDE as a Maven project.  Instructions for running an app scope from a command line or from an IDE as a Maven project can be found at Server Hello World Sample App.  An instructional video on how to build and deploy an Akula app from your IDE can be found at Working With Akula Services Within Your IDE.

    To validate these steps, make a request to this endpoint in a browser: http://localhost:8080/akula/ToDo/data/HelloWorld

  3. Copy and replace the following files from the /ToDoSupportingFiles/akula/ToDo/AKZ-INF/config/scope directory to the directory ToDo/src/main/config/scope:

    File

    Description

    Full Documentation

    apiendpoints.xml

    The API config is effectively the front end of your Akula Server app. Each endpoint URL executes a set of actions (called a route) based on the HTTP verb used to make the request. The definition of these routes can be found in routeconfig.xml. Endpoints created in this config file can be called by a URL in the following format:

    http://[domain]:[port]/[Akula Server]/[app scope name]/data/[endpoint]

    This format creates the endpoints that the ToDo app uses. These include GET, POST, PUT, and DELETE verbs to perform CRUD actions on tasks.

    Using Endpoints

    routeconfig.xml

    The routeconfig.xml contains routes that are referenced in the apiendpoints.xml. Routes are a series of commands to be executed in series (parallel execution is also possible). Each step in a route executes a module with a given set of instructions (everything following the ://). Some modules, like akhttp and aksql, are pointed at separate module configuration file to perform more complex actions.

    This creates the routes which the ToDo app uses.  Each route performs a CRUD operation using the HTTP module to interact with the RESTful datasource.


    Using Routes

    permissions.xml

    Permissions provide special authorization to endpoints defined in apiendpoints.xml.

    This creates the permissions which the ToDo app uses. For instance, some users will be able to perform CRUD operations on a task while others will only be able to read tasks.

    Authentication and Authorization Overview

    properties.xml

    This creates the properties which the ToDo app uses. For this example, you are interested in overriding the <akula_security_manager> to use a separate SQLite database of users and to set the baseurl property to be used within the HTTP module.

    The ToDo app is configured by default with an App Property baseurl of http://localhost:8080/todo-rest which is used as the base URL for all the data source RESTful endpoints.  If the data source deployed above can be browsed to via this URL, no action is required.  If the data source was deployed to a different location or your server uses a different port, you will need to change the base URL in the ToDo app as follow:

    1. Open the properties.xml file you just copied to ToDo/src/main/config/scope

    2. Change the <custom-property key="baseurl"> from http://localhost:8080/todo-rest to http://[domain]:[port]/todo-rest

    Defining App Properties

  4. Copy the akhttpconfig.xml file from the /ToDoSupportingFiles/akula/ToDo/AKZ-INF/config/module directory to the ToDo/src/main/config/module directory.

    The akhttpconfig.xml file instructs the HTTP module how to make requests to REST, WSDL, or SOAP web services to retrieve data. Properties from the properties.xml are commonly used here to abstract out the domain of web services being accessed for easy switching between environments. Each HTTP module configuration is referenced in a routeconfig.xml by the key attribute.

    This is the HTTP module configuration that the ToDo app uses and describes how the akhttp module interacts with the RESTful datasource

    For full documentation on the HTTP Module see HTTP Module.
     
  5. Rebuild and re-deploy the ToDo app scope from a command line or from an IDE as a Maven project.  Instructions for running an app scope from a command line or from an IDE as a Maven project can be found at Server Hello World Sample App.  An instructional video on how to build and deploy an Akula app from your IDE can be found at Working With Akula Services Within Your IDE.

  6. Copy and replace the following files from the /ToDoSupportingFiles/akula directory to the directory AKULA_HOME/global:

    File

    Description

    Full Documentation

    security-template.xml

    This creates the Security Manager that the ToDo app uses and describes the security realm the app authenticates against.

    For the ToDo app, you will be using a JDBC database as the authentication realm.

    Defining a Security Manager

    users.db

    This is the SQLlite database that the app acts as the security directory the app authenticates against.

     

    The AKULA_HOME environment variable will have been set automatically by the Akula installer. By default, it will point to the /home directory within the path you specified during the Akula installer. For example, for Mac OS it might be:

    /Users/jsmith/Akula/home/

      

  7. Restart the Java app server to apply your changes.

  8. Configure the roles used by the ToDo app.

    Before users can access the ToDo app, you must create the roles used by the Akula authorization mechanism. Roles associate user groups with permissions to control access to the app.

    The Akula automated installer installs the Akula Command-line Management Utility.  The Akula Command-line Management Utility is a command-line utility that lets you configure the Akula Server and apps running on the server.  For more information on using the Akula Command-line Management Utility, see Using the Akula Command-line Management Utility.

    For Microsoft Windows:


    1. From the location where you unzipped the ToDoSupportingFiles.zip file, copy the ToDoSupportingFiles/akula/ToDoPermissions.txt file to the directory where the Akula Command-line was installed. This directory is typically /server-sdk/tools/mgmt-util/bin.

    2. In a Command Prompt, change directories to the directory where you installed the Akula Command-line.
    3. Execute the following command to create the roles and permissions used by the samples and tutorials:

      > akula.exe -s ToDoPermissions.txt http://localhost:8080/akula

    For Mac OS X and Linux:

    1. From the location where you unzipped the ToDoSupportingFiles.zip file, copy the ToDoSupportingFiles/akula/ToDoPermissions.txt file to the directory where the Akula Command-line was installed. This directory is typically /server-sdk/tools/mgmt-util/src.

    2. In a Command Prompt, change directories to the directory where you installed the Akula Command-line.
    3. Execute the following command to create the roles and permissions used by the samples and tutorials:

      > python akula.py -s ToDoPermissions.txt http://localhost:8080/akula
       
         

  9. The Akula Server configuration for the ToDo app is now complete!  You can now try hitting one of the ToDo app's endpoints to validate that it returns correctly. But, if you try hitting the endpoint directly in a browser, you'll actually receive an ACCESS_DENIED response, since the app has authentication enabled. So, to validate your setup, try using a tool like the Postman Chrome extension to send two sample requests:

    Login:

    PropertyValue
    Endpoint URLhttp://localhost:8080/akula/ToDo/auth/sessions
    MethodPOST
    Request parameters

    {
      "principal": "leonard",
      "secret": "leonard"

    }

    Request headers
    Accept:"application/json"
    Content-Type:"application/json"
    Example response body

    {
      "token":"uuid",
      "timeout":1800000,

      "user": {
        "id":"myusername",
        "realm":"realmName",
           "info": {
          "firstname":"fname",
          "lastname":"lname",
          "fullname":"fullname"
          }

       
    },

      "properties": {
        "propname":"propval",
        "propname2":"propval2"
      },
      "permissions": [
        "perm1",
        "perm2"],
      "status": {
        "akula-server-version": "x.y.z"
     
    }
    }


    Get Tasks:

    PropertyValue
    Endpoint URLhttp://localhost:8080/akula/ToDo/data/tasks
    MethodGET
    Request parameters

    None

    Request headers

    X-Ak-Session-Id:token (session token returned by a successful log in in above request)

    Example response body[
        {
            "id": "353c1bbd-6541-4c67-a5b7-dec7289fac27",
            "name": "Install Tomcat",
            "due": 1372428793390,
            "complete": 0
        },
        {
            "id": "9b9d1809-e82b-4b4c-90ea-ebcaea0d1ba1",
            "name": "Deploy Akula",
            "due": 1372428793473,
            "complete": 0
        },
        {
            "id": "5e078527-2787-448a-8c8b-f96b5356973b",
            "name": "Build an app",
            "due": 1372428793475,
            "complete": 0
        }
    ]

    If you run into any issues while trying reach the Get Tasks endpoint, please make sure the ToDo's app property baseurl is set correctly to reflect the base URL for the data source's RESTful endpoints on your Java server. If you have any trouble, further documentation on this setup can be found here: Configuring your local environment for the ToDo app.

      

  10. Build the ToDo client app by using the following instructions for each platform:

    iOS: ToDo iOS Client App
    Android: ToDo Android Client App
    JavaScript: ToDo JavaScript Client App

Congratulations! You should now be able to run the ToDo client app to login and interact with the Akula Server you just configured. For more information on using the ToDo app see Using the ToDo App. Feel free to expand on this exercise by enhancing and adding functionality to both the Akula Server configuration and client code.