Quick Start Guide

Top  Previous  Next

This Quick Start guide will walk you through the process of creating a Backendless API service by uploading Java code to API Engine. By the time you finish the guide, you will have a working API service hosted in Backendless API Engine. You will be able to experience REST-based method invocations and download generated client SDKs.

Requirements

Before you start with the guide, you will need the following:

1.Java Development Kit (JDK) version 7 or above.
2.Java development environment (IntelliJ IDEA, Eclipse, etc), we recommend IDEA.
3.a Backendless account, register for your free account at http://develop.backendless.com/#registration
4.Backendless Code Runner for Java, download from the Backendless website. Expand the downloaded zip file into a directory. As a convention, that directory will be referenced in the subsequent instructions as <CODERUNNER-DIR>.

Service Design

The service developed in this guide is a trivialized shopping cart. The APIs generated by API Engine from the code will allow adding items to the shopping cart, retrieving and deleting the contents of the cart. It is important to remember that each operation of the service must be stateless, as a result, any intermediary state between the service calls must be stored elsewhere (persistent storage, cache, etc). In the design of the code, the state is the actual shopping cart object and it will be stored in Backendless Cache. Every method call will be retrieving the cart from cache, updating the cart object as necessary and then placing it back into cache. The code will identify every shopping cart by logical name, thus the same service will be able to handle multiple cart objects.

Service Development

Backendless provides a pre-packaged service code which makes steps 1-6 optional. If you would like to use the pre-packaged code, skip to step 7.

1.Create a new Java library project and add add <CODERUNNER-DIR>/lib/backendless.jar as a dependency.
backendless-jar-dependency.zoom60
 
2.Create a Java class called ShoppingCartService in the com.mbaas.service package. The name of the package is not important, as long as there is one. Make sure the class implements the com.backendless.servercode.IBackendlessService interface. The interface does not have any methods and serves the purpose of a marker - indicating to API Engine that the class must be processed as an API service.
package com.mbaas.service;

import com.backendless.servercode.IBackendlessService;

public class ShoppingCartService implements IBackendlessService
{
}
3.Before we proceed with the service, it is important to define the classes the service will be operating on. These include the ShoppingCart and the ShoppingItem classes. Create the classes with the code shown below:
 
ShoppingItem class:
package com.mbaas.shopping;

public class ShoppingItem
{
    public String objectId;
    public String product;
    public float price;
    public int quantity;
}

ShoppingCart class:
package com.mbaas.shopping;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

public class ShoppingCart
{
  private List<ShoppingItem> items = new ArrayList<>();

  public void addItem( ShoppingItem item )
  {
    items.add( item );
  }

  public List<ShoppingItem> getItems()
  {
    return items;
  }

  public boolean deleteItem( String productName )
  {
    Iterator<ShoppingItem> iterator = items.iterator();

    while( iterator.hasNext() )
    {
      ShoppingItem item = iterator.next();

      if( item.product.equals( productName ) )
      {
        iterator.remove();
        return true;
      }
    }

    return false;
  }
}
4.Return to the service class and add the method shown in the code below. The method is private and will be used by other methods added in the subsequent steps. The method is responsible for retrieving a ShoppingCart object from Backendless cache.
package com.mbaas.service;

import com.backendless.servercode.IBackendlessService;
import com.backendless.Backendless;

public class ShoppingCartService implements IBackendlessService
{
  private ShoppingCart getCart( String cartName )
  {
    if( cartName == null || cartName.trim().length() == 0 )
      throw new IllegalArgumentException( "Missing cart name" );

    return Backendless.Cache.get( cartName, ShoppingCart.class );
  }
}
5.Add the addItem, deleteItem and getItems methods which will become API operations once the code is deployed to API Engine. Every method expects the name of the cart, which is how a ShoppingCart object stored in cache is identified. A cart is retrieved from cache. If it is not in cache (which means it would be the first request for the cart), it is created. Once a cart is updated in the addItem, deleteItem methods, it is placed back into cache.
package com.mbaas.service;

import com.backendless.Backendless;
import com.backendless.servercode.IBackendlessService;
import java.util.List;

public class ShoppingCartService implements IBackendlessService
{
  public void addItem( String cartName, ShoppingItem item )
  {
    ShoppingCart shoppingCart = getCart( cartName );

    if( shoppingCart == null )
      shoppingCart = new ShoppingCart();

    shoppingCart.addItem( item );
    item.objectId = null;
    Backendless.Cache.put( cartName, shoppingCart );
  }
  
  public boolean deleteItem( String cartName, String productName )
  {
    ShoppingCart shoppingCart = getCart( cartName );

    if( shoppingCart == null )
      return false;

    boolean result = shoppingCart.deleteItem( productName );
    Backendless.Cache.put( cartName, shoppingCart );
    return result;
  }

  public List<ShoppingItem> getItems( String cartName )
  {
    ShoppingCart shoppingCart = getCart( cartName );

    if( shoppingCart == null )
      shoppingCart = new ShoppingCart();

    return shoppingCart.getItems();
  }

  private ShoppingCart getCart( String cartName )
  {
    if( cartName == null || cartName.trim().length() == 0 )
      throw new IllegalArgumentException( "Missing cart name" );

    return Backendless.Cache.get( cartName, ShoppingCart.class );
  }
}
6.Compile the code and package all the compiled class files into a .jar file. The name of the file is not important, let's assume it is call ShoppingCartService.jar.
 
The created jar file must not contain any classes from backendless.jar. If this rule is not maintained, deployed services cannot be invoked.
 
7.Login to Backendless console, select your app and click the Business Logic icon. The Hosted menu under the API Services section is selected by default.
hosted-services-biz-logic.zoom50
 
8.Click the New Hosted Service button. Enter information into the fields as shown below. Click the Browse... button and locate ShoppingCartService.jar created in step 6. Alternatively, you can use the pre-packaged service jar by clicking the use sample 'shopping cart' service checkbox. Click the Save button.
shopping-cart-service
 
9.Once the jar file is uploaded to Backendless, it is processed and the service APIs along with the SDKs are generated. Backendless Console will then display available operations in API Inspector (if you used the pre-packaged 'shopping cart' service, you will see additional methods):
deployed-service-methods.zoom50
 
10. Click the pop-out icon for API Inspector to open it in an pop-up window:
api-inspector-popup
 
11. The API Inspector lists all operations available in the service. To see details of an operation, click its name. For example, click the /addItem method. The details of a method include a listing of its parameters. Backendless automatically inserts the following parameters for every method: application-id, secret-key and user-token. The first two are mandatory, the values for them can be obtained from the Manage > App Settings screen of the Backendless Console. The user-token parameter is optional. If it is present, it must contain the user token value obtained from the result of the login API call. All three parameters must be formatted as HTTP headers.
 
In addition to the parameters injected by Backendless, the user interface lists any formal method arguments and their corresponding schema. For example, the /addItem method has an argument which combines the shopping cart name and the item being added to the cart. To remind you, the Java addItem method has the following signature:
public void addItem( String cartName, ShoppingItem item )

When Backendless generates the REST API, it combines formal method arguments into a single JSON object which must be sent in the body of the request. For the addItem method, the REST operation argument is:
{
  "cartName": "string",
  "item": {
    "objectId": "string",
    "product": "string",
    "price": 0,
    "quantity": 0
  }
}
12.To invoke the addItem method from API Inspector, you will need to provide argument value. The starting point may be clicking the model schema area so its contents are copied to the argument value area:
click-schema.zoom50
 
13.Modify the argument value as shown below. The objectId element can be removed, it is not needed for this operation.
{
  "cartName": "my cart",
  "item": {
    "product": "Hoverboard",
    "price": 499,
    "quantity": 1
  }
}
14.Click Try it out to make an invocation of the method:
try-it-now.zoom50
 
15. Notice the output displays a complete curl request which executes the same REST API request. There is also Request URL, Response Code and Response HTTP headers.
 
16.To see the contents of the shopping cart, click the GET /Items method:
get-items-method.zoom50
 
17.Make sure to enter a value for the cartName parameter. The value must be entered in double quotes as shown below:
shopping-cart-name
 
18.Click Try it out! to invoke the GET /Items method.
get-items-result.zoom50
 
The result is a JSON array of ShoppingItem objects (so far there is only one in the collection). This maps closely to the formal response type of the getItems() method in Java:
public List<ShoppingItem> getItems( String cartName )

Now that you have experienced publishing code to API Engine and making API invocations, you should try and explore other capabilities:

1.Deploy the sample 'shopping cart' service. Invoke the GET /Instructions method and follow the instructions received in the method return value.
2.Make a change in the service you built in the steps 1-6 above. Create an updated jar file. Click the service name, modify the version number and deploy the updated jar file. You will have two versions of the same service.

Please let us know how we can improve the documentation by leaving a comment. All technical questions should be posted to the Backendless Support forum. We do not respond to the technical questions on the documentation pages.: