Issuing HTTP(S) Requests

Python 2.7/3.7 | Java 8 |PHP 5.5/7.2 |Go 1.9/1.11 |Node.js

This page describes how to issue HTTP(S) requests from your App Engine app.

Java 8 runtime vs Java 7 behavior

Applications running in the Java 8 runtime by default use standard Java classes, such as java.net.HttpURLConnection for HTTP(S) requests. You send requests just as you would for any other Java application.

When your app runs in Java 8 using default behavior, you must enable your application for billing, or you will get the following exceptions:

• java.net.UnknownHostException
• java.net.SocketTimeoutException
• java.io.IOException

Despite the requirement to enable your application for billing, your app won't incur any more cost than the same application running on Java 7.

Applications running in the deprecated Java 7 runtime also make calls using standard Java classes such as java.net.HttpURLConnection. However, in the Java 7 runtime, those calls are actually handled by the URL Fetch service. Instead of the standard Java calls, Java 7 applications have the option of using the App Engine URL Fetch API to use the URL Fetch service directly.

Using standard Java 8 runtime network classes

If you use the standard Java network classes in the Java 8 runtime, your app will have access to the following features:

• The 32 MB limit on request data is removed
• Support for HTTP 2.0
• Supports all Google Cloud-based APIs accessible from the Google Cloud Client Library for Java.

Using URLFetch in a Java 8 app

If you have to use URL Fetch in a Java 8 app, add the following line to your appengine-web.xml:

 <url-stream-handler>urlfetch</url-stream-handler>

For example:

<xml version="1.0" encoding="utf-8">
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>

Notice that this setting does not require the app to be enabled for billing.

Note: The metadata server can only be accessed using native Java sockets and the native stream handler and does not support the urlfetch service.

Issuing an HTTP request

You issue an outbound HTTP request using java.net.URLConnection.

The following snippet demonstrates how to perform a basic HTTP GET request. The application creates a new URL object, then calls the object's openStream() method to retrieve the content at that URL:

Java 8

appengine-java8/urlfetch/src/main/java/com/example/appengine/UrlFetchServlet.java

View on GitHub

URL url = new URL("http://api.icndb.com/jokes/random");
BufferedReader reader = new BufferedReader(new InputStreamReader(url.openStream()));
StringBuffer json = new StringBuffer();
String line;

while ((line = reader.readLine()) != null) {
  json.append(line);
}
reader.close();

Java 7

appengine/urlfetch/src/main/java/com/example/appengine/UrlFetchServlet.java

View on GitHub

URL url = new URL("http://api.icndb.com/jokes/random");
BufferedReader reader = new BufferedReader(new InputStreamReader(url.openStream()));
StringBuffer json = new StringBuffer();
String line;

while ((line = reader.readLine()) != null) {
  json.append(line);
}
reader.close();

For more advanced requests, use java.net.HttpURLConnection as follows:

1. Create a new URL object.
2. Create a new URLConnection object by calling your URL object's openConnection() method.
3. Create a new HttpURLConnection object by casting your URLConnection object to the HttpURLConnection object type.
4. Set the HttpURLConnection object's request method.
5. Create an output stream for the request.
6. Write the request payload to the stream.
7. Close the stream.

The following snippet demonstrates how to use HttpURLConnection to perform a more advanced request, submitting data from a web form via a PUT request:

Java 8

appengine-java8/urlfetch/src/main/java/com/example/appengine/UrlFetchServlet.java

View on GitHub

URL url = new URL("http://jsonplaceholder.typicode.com/posts/" + id);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("PUT");

OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream());
writer.write(URLEncoder.encode(jsonObj.toString(), "UTF-8"));
writer.close();

int respCode = conn.getResponseCode(); // New items get NOT_FOUND on PUT
if (respCode == HttpURLConnection.HTTP_OK || respCode == HttpURLConnection.HTTP_NOT_FOUND) {
  req.setAttribute("error", "");
  StringBuffer response = new StringBuffer();
  String line;

  BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));
  while ((line = reader.readLine()) != null) {
    response.append(line);
  }
  reader.close();
  req.setAttribute("response", response.toString());
} else {
  req.setAttribute("error", conn.getResponseCode() + " " + conn.getResponseMessage());
}

Java 7

appengine/urlfetch/src/main/java/com/example/appengine/UrlFetchServlet.java

View on GitHub

URL url = new URL("http://jsonplaceholder.typicode.com/posts/" + id);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("PUT");

OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream());
writer.write(URLEncoder.encode(jsonObj.toString(), "UTF-8"));
writer.close();

int respCode = conn.getResponseCode();  // New items get NOT_FOUND on PUT
if (respCode == HttpURLConnection.HTTP_OK || respCode == HttpURLConnection.HTTP_NOT_FOUND) {
  req.setAttribute("error", "");
  StringBuffer response = new StringBuffer();
  String line;

  BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));
  while ((line = reader.readLine()) != null) {
    response.append(line);
  }
  reader.close();
  req.setAttribute("response", response.toString());
} else {
  req.setAttribute("error", conn.getResponseCode() + " " + conn.getResponseMessage());
}

Setting a request timeout

If you are using URL Fetch, you can adjust the default deadline for requests using the appengine.api.urlfetch.defaultDeadline setting in the appengine-web.xml file.

Setting headers

If you are using URL Fetch, you can set an HTTP header on the outgoing request, by calling your HttpURLConnection object's setRequestProperty() method. The following snippet sets the X-MyApp-Version header to 2.7.3:

conn.setRequestProperty("X-MyApp-Version", "2.7.3");

Disabling redirects

By default, HttpURLConnection follows HTTP redirects. If you are using URL Fetch, the underlying URL Fetch service will follow up to five redirects. To disable this behavior, pass the value false to your HttpURLConnection object's setInstanceFollowRedirects() method:

conn.setInstanceFollowRedirects(false);

If your app uses the underlying urlfetch package directly instead of java.net, your app must specify doNotFollowRedirects.

Issuing an HTTPS request

If you are using URL Fetch, issue an HTTPS request using the FetchOptions class in the urlfetch package and call validateCertificate().

Issuing an asynchronous request

HTTP(S) requests are synchronous by default. To issue an asynchronous request, your application must use URLFetchService's fetchAsync() method. This method returns a java.util.concurrent.Future<HTTPResponse>.

Issuing a request to another App Engine app

When issuing a request to another App Engine app, your App Engine app must assert its identity by adding the header X-Appengine-Inbound-Appid to the request. If you instruct the URL Fetch service to not follow redirects, App Engine will add this header to requests automatically. See Disabling redirects for guidance on disabling redirects.

Note: If you are making requests to another App Engine application, use its appspot.com domain name rather than a custom domain for your app.

What's next

Learn about the URL Fetch service, such as the headers that are sent in a URL Fetch request in Outbound Requests.