message: docs: Add a note about readUrl with read
diff: @@ -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.
  