Overview

This example shows you how to make App Services calls with standard jQuery ajax calls. If you need a more comprehensive JavaScript SDK that is not platform dependent, consider our HTML5 Javascript SDK.

You can find the source for the example at:

https://github.com/apigee/Usergrid-jQuery-Example

To view a live demo of this example, see:

http://apigee.github.com/Usergrid-jQuery-Example/

The JavaScript file

The main file for this example is js/app.js. The file is where all the JavaScript code for the example resides and where all calls to the API are made. You'll find the following code on line 32 of the file:

//Your org and app combination - change this!!
var org = 'apigee'; //<== your organization
var app = 'sandbox';//<== your application

Replace the values for the org and app variables with the organization and application names for your account, so that when you run the code it will connect to the correct account.

The main functions are _get, _post, _put, and _delete. These functions accept their input from a form, and then call the apiRequest() method. The apiRequest() method makes a call to the server.

Note: This example uses the "sandbox" application that comes with your new account. The sandbox app does not require authentication tokens and this jQuery example doesn't use them. However, you can easily extend the example to require authentication tokens. That's because the code to add the token to the header is in the apiRequest() method.

The App

The app supports all four call types (GET, POST, PUT, and DELETE). Select the method you want to run by pressing one of the four buttons in the live demo.

GET

If you click the GET button, you'll see a GET screen that displays a Path input field, a Run Query button, and an API Response output field. To submit a GET request, enter into the Path field the path of the endpoint you want to retrieve. For example, to get all users, enter:

/users

To get a specific user, enter:

/users/username

You may want to append query parameters to the end of the URL for things like searching. Simply append those to the "path"entry like this:

/users?ql=select * where username = 'fred*'

Click Run Query. Your entry is translated into a URL-encoded string and then sent to the API. The string will look like this:

/users%3Fql%3Dselect%20*%20where%20username%20%3D%20'fred*'

This translation happens in the apiRequest() method when the AJAX request is prepared:

url: apiUrl + encodeURIComponent(path), 

POST

The POST method takes both a path and a request body (in JSON format). So in addition to the Path input field, you'll see an input field to enter the JSON request body. For example, to create a new user, enter the path:

/users

and a request body that contains at least a username:

{"username":"fred"}

This combination will create a new user with a username of "fred".

PUT

PUT entry works the same as POST -- enter a path and request body. For example, to update the user "fred", enter a path like this:

/users/fred

and a request body like this:

{"othervalue":"12345"}

This will update or add a key called "othervalue" with a value of "12345" to the entity.

DELETE

Submitting a DELETE request is similar to the way you enter a GET request in that it only takes a path, and no request body. Simply specify the path to the entity you want to delete:

/users/fred

This will delete the user entity with the username of "fred".

Under the hood

The code in this example is standard JavaScript and jQuery. The most interesting part is likely the section of code that makes the calls to the API.

As mentioned above, all calls are eventually routed to the apiRequest() method. This method does three things. First, it prepares the AJAX options:

var ajaxOptions = {
  type: method.toUpperCase(),
  url: apiUrl + encodeURIComponent(path),
  success: success,
  error: error,
  data: data || {},
  contentType: "application/json; charset=utf-8",
  dataType: "json"
}

Second, it appends an OAuth token if one is available. These lines are not currently used as this example never uses a token. But, thay are included here to show you how you to add the token if your app uses one:

ajaxOptions.beforeSend = function(xhr) {
    if (accessToken) { xhr.setRequestHeader("Authorization", "Bearer " + session.accessToken) }
}

The third thing it does is make the AJAX call via jQuery:

$.ajax(ajaxOptions);

Known issues

This code (that is, the jQuery ajax function) will not fully work with a version of Internet Explorer prior to version 10. In version 10, Microsoft implemented XMLHttpRequest which makes all the magic possible.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)