diff --git a/docs/integrations/url-reader.md b/docs/integrations/url-reader.md
index 23500a3dcb..83f6a743d9 100644
--- a/docs/integrations/url-reader.md
+++ b/docs/integrations/url-reader.md
@@ -149,6 +149,8 @@ remaining.
 
 #### read
 
+NOTE: Use `readUrl` instead of `read`.
+
 `read` method expects a user-friendly URL, something which can be copied from
 the browser naturally when a person is browsing the provider in their browser.
 
@@ -164,6 +166,13 @@ which can be used to request the provider's API.
 `read` then makes an authenticated request to the provider API and returns the
 file's content.
 
+#### readUrl
+
+`readUrl` is a new interface that allows complex response objects and is
+intended to replace the `read` method. This new method is currently optional to
+implement which allows for a soft migration to `readUrl` instead of `read` in
+the future.
+
 #### readTree
 
 `readTree` method also expects user-friendly URLs similar to `read` but the URL
@@ -197,12 +206,11 @@ the tree and return the files matching the pattern in the `url`.
 
 ### Caching
 
-All of the methods above support an ETag based caching (except `read` which is
-work in progress!). If the method is called without an `etag`, the response
-contains an ETag of the resource (should ideally forward the ETag returned by
-the provider). If the method is called with an `etag`, it first compares the
-ETag and returns a `NotModifiedError` in case the resource has not been
-modified. This approach is very similar to the actual
+All of the methods above support an ETag based caching. If the method is called
+without an `etag`, the response contains an ETag of the resource (should ideally
+forward the ETag returned by the provider). If the method is called with an
+`etag`, it first compares the ETag and returns a `NotModifiedError` in case the
+resource has not been modified. This approach is very similar to the actual
 [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) and
 [If-None-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match)
 HTTP headers.