Issue HTTPS requests

Go Java PHP Python

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

OK

This page describes how to issue HTTP(S) requests from your App Engine app using the URL Fetch service for second-generation runtimes.

Before following the instructions on this page, we recommend you use language idiomatic solutions to issue HTTP(S) requests before using the URL Fetch service. The primary use case for using the URL Fetch is when you want to issue HTTP(S) requests to another App Engine app and assert your app's identity on that request.

For details on request size limits and which headers are sent in a URL Fetch request, see Outbound requests.

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

Use standard runtime network classes

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

• The 32 MB limit on request data doesn't apply.
• Support for HTTP 2.0.
• Supports all Google Cloud-based APIs accessible from the Cloud Client Libraries for Java.

Use URL Fetch

Warning: Don't use URL Fetch if you have set up Serverless VPC Access or use Cloud Client Libraries for Java. URL Fetch handles all outbound requests, and requests that you send to your VPC network or the client libraries fail. If any of these scenarios apply to you, make sure that you don't set the url-stream-handler field in your configuration to urlfetch. Apps that use Cloud Client Libraries for Java and attempt to use URL Fetch through the URLConnection wrapper aren't supported.

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

 <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>

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

Issue an HTTP request

To use the URL Fetch service to issue outbound HTTP(S) requests, use the 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:

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, and submit data from a web form using a PUT request:

URL url = new URL("http://jsonplaceholder.typicode.com/posts/" + id);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
// Enable output for the connection.
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
conn.setRequestProperty("Accept", "application/json");
// Set HTTP request method.
conn.setRequestMethod("PUT");

// Create JSON request.
JSONObject jsonObj =
    new JSONObject().put("userId", 1).put("id", id).put("title", text).put("body", text);

OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream());
writer.write(jsonObj.toString());
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", "");
  StringBuilder response = new StringBuilder();
  String line;

  // Read input data stream.
  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());
}

Set a request timeout

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

Set 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");

Disable redirects

Important: To improve the security of your app, it is recommended that you disable redirects.

By default, HttpURLConnection follows HTTP redirects.

If you are using URL Fetch, the underlying URL Fetch service follows up to five redirects by default. These redirects could forward sensitive information, such as authorization headers, to the redirected destination. If your app does not require HTTP redirects, it is recommended that you disable the 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.

Issue an HTTPS request

By default, the underlying URL Fetch service validates the certificate of the host it contacts, and rejects requests if the certificate doesn't match. You don't need to explicitly secure your request.

Disable host certificate validation

To disable automatic host certificate validation in URL Fetch, issue an HTTPS request using the FetchOptions class in the urlfetch package and call the doNotValidateCertificate() method.

Issue 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>.

Issue a request to another App Engine app

When using URL Fetch to issue a request to another App Engine app, your app can 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 REGION_ID.r.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.