Edit this page

up.network up.request([url], [options])
JavaScript function

Makes an AJAX request to the given URL.

Returns an up.Request object which contains information about the request. This request object is also a promise for an up.Response that contains the response text, headers, etc.

Example

let request = up.request('/search', { params: { query: 'sunshine' } })
console.log('We made a request to', request.url)

let response = await request
console.log('The response text is', response.text)

Error handling

The returned promise will fulfill with an up.Response when the server responds with an HTTP status of 2xx (like 200).

When the server responds with an HTTP error code (like 422 or 500), the promise will reject with up.Response.

When the request fails from a fatal error (like a timeout or loss of connectivity), the promise will reject with an Error object.

Here is an example for a complete control flow that handles both HTTP error codes and fatal errors:

try {
  let response = await up.request('/search', { params: { query: 'sunshine' } })
  console.log('Successful response with text:', response.text)
} catch (e) {
  if (e instanceof up.Response) {
    console.log('Server responded with HTTP status %s and text %s', e.status, e.text)
  } else {
    console.log('Fatal error during request:', e.message)
  }
}

Caching

You may cache responses by passing a { cache } option. Responses for a cached request will resolve instantly.

See Caching for more details and examples.


Parameters

[url] string optional

The requested URL.

Instead of passing the URL as a string argument, you can also pass it as an { url } option.

[options.url] string optional

The requested URL.

[options.method='GET'] string optional

The HTTP method for the request.

[options.params={}] Objectorup.ParamsorFormDataorstringorArray optional

Parameters that should be sent as the request's query string or payload.

When making a GET request to a URL with a query string, the given { params } will be added to the query parameters.

[options.cache=false] boolean optional

Whether to read from and write to the cache.

With { cache: true } Unpoly will try to re-use a cached response before connecting to the network. If no cached response exists, Unpoly will make a request and cache the server response.

With { cache: 'auto' } Unpoly will use the cache only if up.network.config.autoCache returns true for this request.

With { cache: false } (the default) Unpoly will always make a network request.

[options.expireCache] booleanorstring optional

Whether to expire the cache after this request.

Defaults to the result of up.network.config.expireCache, which defaults to expiring the entire cache after a non-GET request.

You may also pass a URL pattern to only expire matching responses.

[options.evictCache] booleanorstring optional

Whether to evict the cache after this request.

Defaults to the result of up.network.config.evictCache, which defaults to false.

You may also pass a URL pattern to only evict matching responses.

[options.headers={}] Object optional

An object of additional HTTP headers.

Unpoly will by default send a number of custom request headers. See up.protocol for details.

[options.wrapMethod] boolean optional

Whether to wrap non-standard HTTP methods in a POST request.

If this is set, methods other than GET and POST will be converted to a POST request and carry their original method as a _method parameter. This is to prevent unexpected redirect behavior.

Defaults to up.network.config.

[options.timeout] string optional

A timeout in milliseconds.

If the request is queued due to many concurrent requests, the timeout will not include the time spent waiting in the queue.

[options.target='body'] string optional

The CSS selector that will be sent as an X-Up-Target header.

The targets of concurrent requests to to same URL may be merged.

[options.failTarget='body'] string optional

The CSS selector that will be sent as an X-Up-Fail-Target header.

[options.layer='current'] string optional

The layer this request is associated with.

If this request is intended to update an existing fragment, this is that fragment's layer.

If this request is intended to open an overlay, the associated layer is the future overlay's parent layer.

[options.failLayer='current'] string optional

The layer this request is associated with if the server sends a HTTP status code.

[options.origin] Element optional

The DOM element that caused this request to be sent, e.g. a hyperlink or form element.

[options.contentType] Element optional

The format in which to encode the request params.

Allowed values are application/x-www-form-urlencoded and multipart/form-data. Only multipart/form-data can transport binary data.

If this option is omitted Unpoly will prefer application/x-www-form-urlencoded, unless request params contains binary data.

[options.payload] string optional

A custom payload for this request.

By default Unpoly will build a payload from the given { params } option. Therefore this option is not required when making a standard link or form request to a server that renders HTML.

A use case for this option is talking to a JSON API that expects requests with a application/json payload.

If a { payload } option is given you must also pass a { contentType }.

[options.background=false] boolean optional

Whether this request will load in the background.

Background requests deprioritized over foreground requests. Background requests also won't emit up:network:late events and won't trigger the progress bar.

[options.badResponseTime] number optional experimental

The number of milliseconds after which this request can cause an up:network:late event.

Defaults to up.network.config.badResponseTime.

Return value

An object with information about the request.

The request object is also a promise for its up.Response.