REST Routes

Backendless supports two ways for creating REST API routes:

1. Service code explicitly declares REST routes.
2. Generate REST routes based on the method signatures in the service class.

REST Routes from Explicit Declaration

JavaScript code can use the JSDoc comments to annotate code with information about REST routes. Consider the following example:

class HelloService {
 /**
  * @route POST /say/hello
  */
  helloWorld( ) {
    return "hello";
  }
}

Backendless.ServerCode.addService( HelloService );

Notice the @route annotation in the comment for the helloWorld method. When the service is deployed to Backendless, the REST route associated with the method will be built as shown below:

POST https://api.backendless.com/<App ID>/<REST API key>/services/<service name>/<service version>/say/hello

The general format for a service API route is:

POST https://api.backendless.com/<App ID>/<REST API key>/services/<service name>/<service version>/<path from @route>

where:

Argument	Description
<App ID>	Application ID from theManage > App Settings screen in Backendless Console.
<REST API Key>	REST API Key for the application from theManage > App Settings screen in Backendless Console.
<service name>	Service name as shown in Backendless Console. Service name is the same as the name of the service class.
<service version>	Version number/name assigned to service at the time when code is uploaded/published to Backendless.
<path from @route>	Path specified in the @route comment for the method.

The @route annotation has the following syntax:

@route GET | POST | PUT | DELETE /<path>

If HTTP operation (GET|POST|PUT|DELETE) is not specified, the route is GET by default.

The /<path> element may include path parameters. The example below declares the {name} path parameter. The parameter's value can be accessed  in the code using this.request.pathParams.<parametername>.

class EchoService {
 /**
  * @route POST /echo/{name}
  */
  sendNameBack( ) {
     return "Hello " + this.request.pathParams.name;
  }
}

Backendless.ServerCode.addService( EchoService );

REST Routes from Method Signatures

Backendless uses the following rules when creating REST APIs from method signatures:

Method's name prefix	HTTP command	Route	Argument(s)
addXXX( T )	POST	///services///XXX	JSON format of T sent in request body
setXXX( T )	PUT	///services///XXX	JSON format of T sent in request body
setXXX( int indexArg, T valueArg )	PUT	///services///XXX	JSON format of indexArg and valueArg in request body: {    "indexArg" : value,    "valueArg" : value }
deleteXXX( T )	DELETE	///services///XXX	JSON format of XXX sent in request body
getXXX()	GET	///services///XXX	n/a
getXXX( int index )	GET	///services///XXX?index=value	The index argument must be sent as a query argument
none of the above - foobar()	POST	///services///foobar

where:

<app ID>        - Application ID from the Manage > App Settings screen in Backendless Console.

<REST API Key>        - REST API Key for the application from the Manage > App Settings screen in Backendless Console.

<service name>- Service name as shown in Backendless Console. Service name is the same as the name of the service class.

<service version>- Version number/name assigned to service at the time when code is uploaded/published to Backendless.

Consider the following service:

'use strict';

class ShoppingService {
  /**
   * @param {ShoppingItem} item
   */
  addItem(item) {
    // skipping implementation for brevity
  }

  /**
   * @param {ShoppingItem} item
   */
  deleteItem(item) {
    // skipping implementation for brevity
  }

  /**
   * @returns {ShoppingItem[]}
   */
  getCartItems() {
    // skipping implementation for brevity
  }

  /**
   * @returns {Number}
   */
  calculateTotal() {
    // skipping implementation for brevity
  }
}

Backendless.ServerCode.addService(ShoppingService);

Assuming the name assigned to the service is ShoppingService and version is 1.0, API Engine generates the following REST API routes for the service:

addXXX method:

JavaScript function:

/**
 * @param {ShoppingItem} item
 */
addItem(item)

REST API:

POST http://api.backendless.com/<API ID><REST API Key>/services/ShoppingService/1.0/Item  
Request body: a JSON object representing ShoppingItem

getXXX method:

JavaScript function:

/**
 * @returns {ShoppingItem[]}
 */
getCartItems()

REST API:

GET http://api.backendless.com/<API ID><REST API Key>/services/ShoppingService/1.0/CartItems

deleteXXX method:

JavaScript function:

/**
* @param {ShoppingItem} item
*/
deleteItem(item)

REST API:

DELETE http://api.backendless.com/<API ID><REST API Key>/services/ShoppingService/1.0/Item

all other methods:

JavaScript function:

/**
 * @returns {Number}
 */
calculateTotal()

REST API:

POST http://api.backendless.com/<API ID><REST API Key>/services/ShoppingService/1.0/calculateTotal