Calling an Endpoints Framework API from a JavaScript App

Cloud Endpoints Frameworks v1 has been deprecated and will be shut down on August 2, 2018. We recommend that you use the latest version of this feature, which is renamed to Cloud Endpoints Frameworks for App Engine. This new version supports App Engine standard environment, provides lower latency, and has better integration with App Engine. For more details, see Migrating to 2.0.

This page describes how to call a backend API built with a Cloud Endpoints Framework from a JavaScript app.

To use an API build with a Google Cloud Endpoints Framework from javascript, you'll need to use the Google JavaScript client library. The code you need to add is minimal, as shown in the following sections.

Enabling a JavaScript client for Endpoints Frameworks APIs

To enable a JavaScript client to use an Endpoints Framework API:

  1. Add the script that includes the Google-hosted JavaScript client library to your HTML:

    <script src="">
  2. Notice that the JavaScript line above includes an onload property specifying the function to be used as a callback after the library loads. Replace "init" with the name of your page initialization function if you did not name it init.

  3. Inside your callback function, load your Endpoint:

gapi.client.load('helloworld', 'v1', callback, apiRoot);
This example loads `helloworld v1` in the JavaScript client library and calls `callback` once the API is loaded.
  1. Replace apiRoot in the above code with the name of your application to load your own APIs. Replace helloworld and v1 with the name and version of your Endpoint backend.

Calling an Endpoints Framework API

Once the JavaScript client is enabled for an Endpoint, you can make calls to that Endpoint using the Google JavaScript client object gapi.client. (For more information, see Getting Started for the google-api-javascript-client.)

The following two calls show an insert and a list request made to the Greetings API:

Add a new greeting:

google.devrel.samples.hello.authedGreeting = function(id) {
      function(resp) {

Get the list of previous greetings:

google.devrel.samples.hello.listGreeting = function() {
      function(resp) {
        if (!resp.code) {
          resp.items = resp.items || [];
          for (var i = 0; i < resp.items.length; i++) {

During development you may want to use the Chrome developer tools JavaScript console, which automatically suggests available method names when you are manipulating gapi.client. With the above example Endpoint, typing gapi.client.tictactoe. into that console results in the Chrome developer tools suggesting scores as a possible completion.

Adding authentication support with OAuth 2.0

Built-in support for OAuth is provided by the JavaScript client library for use with Google APIs and Endpoints.

Authorization is provided by the built-in authorize method. When you want to require a user sign-in, you call the following:

google.devrel.samples.hello.signin = function(mode, callback) {
  gapi.auth.authorize({client_id: google.devrel.samples.hello.CLIENT_ID,
      scope: google.devrel.samples.hello.SCOPES, immediate: mode},


  • CLIENT_ID is the client ID of your application, specified in the clientIds attribute of the @Api (or @ApiMethod) annotation. For more information on getting client IDs, see Adding Authentication to Endpoints.
  • SCOPES are the list of OAuth 2.0 scopes that must be granted to tokens sent to your backend. At minimum, you should request access to the scope: which grants access to the user’s email address.
  • mode is either false or true, depending on whether or not you’d like to present the explicit authorization window to the user. If the user has never authorized your application before, calling authorize with mode: true (no authorization window) will fail. The correct situation to use each modes is described below.
  • callback is the callback function to call once authorize completes.

Sample auth flow for a JavaScript client

Here’s an example flow for authorizing a user in a page using the JS client:

google.devrel.samples.hello.init = function(apiRoot) {
  // Loads the OAuth and helloworld APIs asynchronously, and triggers login
  // when they have completed.
  var apisToLoad;
  var callback = function() {
    if (--apisToLoad == 0) {

  apisToLoad = 2; // must match number of calls to gapi.client.load()
  gapi.client.load('helloworld', 'v1', callback, apiRoot);
  gapi.client.load('oauth2', 'v2', callback);
google.devrel.samples.hello.signin = function(mode, callback) {
  gapi.auth.authorize({client_id: google.devrel.samples.hello.CLIENT_ID,
      scope: google.devrel.samples.hello.SCOPES, immediate: mode},
google.devrel.samples.hello.userAuthed = function() {
  var request = gapi.client.oauth2.userinfo.get().execute(function(resp) {
    if (!resp.code) {
      google.devrel.samples.hello.signedIn = true;
      document.getElementById('signinButton').innerHTML = 'Sign out';
      document.getElementById('authedGreeting').disabled = false;

Note that the code sample assumes init() to be the callback function you provided when loading the JS client library. Inside init(), your API and the OAuth 2.0 API are loaded. After the OAuth 2.0 API is loaded, the sample attempts to authorize the user using immediate mode (no authorization prompt). If immediate mode succeeds, the sample sets the token for future requests to the ID token required by your Endpoint's backend.

If your user has previously authorized your application, the user is signed in, and your application can proceed normally. Authorization headers are automatically supplied with any requests.

If the user has not authorized your application previously (or there is no signed in user in the browser session), you’ll need to call authorize again, without using immediate mode. Because this method triggers a popup, it must be called as a result of a user action in the browser, such as clicking a link or button:

<a href="#" onclick="auth();" id="signinButton">Sign in!</a>

function auth() {
  signin(false, userAuthed);

Signing out

There is no concept of signing out using the JS client library, but you can emulate the behavior if you wish by any of these methods:

  • Resetting the UI to the pre signed-in state.
  • Setting any signed-in variables in your application logic to false
  • Calling gapi.auth.setToken(null);

Testing a JavaScript client against a local development server

You can test your client against a backend API running in production App Engine at any time without making any changes. However, if you want to test your client against a backend API running on the local development server, you'll need to change the javascript origin in the backend API's web client ID.

To make the required changes and test using the local dev server:

  1. Open the Credentials page for your project.
  2. Double-click on your OAuth 2.0 Web client in the client ID list.
  3. In the web client ID form, change the Authorized JavaScript origins field to http://localhost:8080.

  4. Start the local development server, as described in Running and testing API backends locally.

    Make sure you don't change the default port, which is 8080, because this is what you used to set the authorized JavaScript origins previously. (You can change the port if you wish, so long as the authorized JavaScript origins and the local dev server are both set to the same port.)

  5. Test your client as desired.

Sample client source code

For a sample backend API and JavaScript client that illustrates the concepts described above, see the Hello Endpoints sample.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine