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
The requested URL.
Instead of passing the URL as a string argument, you can also pass it as an { url } option.
The requested URL.
The HTTP method for the request.
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.
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.
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.
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.
An object of additional HTTP headers.
Unpoly will by default send a number of custom request headers.
See up.protocol for details.
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.
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.
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.
The CSS selector that will be sent as an X-Up-Fail-Target header.
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.
The layer this request is associated with if the server sends a HTTP status code.
The DOM element that caused this request to be sent, e.g. a hyperlink or form element.
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.
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 }.
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.
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.