Create a more completed readme with examples
diff --git a/pkgs/cupertino_http/README.md b/pkgs/cupertino_http/README.md
index 99dc24a..99e851d 100644
--- a/pkgs/cupertino_http/README.md
+++ b/pkgs/cupertino_http/README.md
@@ -1,5 +1,56 @@
-A macOS/iOS Flutter plugin that provides access to the
-[Foundation URL Loading System](https://developer.apple.com/documentation/foundation/url_loading_system).
+[](https://pub.dev/packages/cupertino_http)
+[](https://pub.dev/packages/cupertino_http/publisher)
-See [DEVELOPMENT.md](DEVELOPMENT.md) for information on how to develop
-the plugin itself.
+A macOS/iOS Flutter plugin that provides access to the
+[Foundation URL Loading System][].
+
+Using the [Foundation URL Loading System][], rather than the socket-based [dart:io HttpClient][] implemententation, has several advantages:
+
+1. It automatically supports iOS/macOS platform features such VPNs and HTTP proxies.
+2. It supports many more configuration options such as only allowing access through WiFi and blocking cookies.
+3. It supports more HTTP features such as HTTP/3 and custom redirect handling.
+
+## Using
+
+The easiest way to use this library is via the the high-level interface defined by [package:http Client][].
+
+This approach allows the same HTTP code to be used on all platforms, while still allowing platform-specific setup.
+
+```dart
+late Client client;
+if (Platform.isIOS) {
+ final config = URLSessionConfiguration.ephemeralSessionConfiguration()
+ ..allowsCellularAccess = false
+ ..allowsConstrainedNetworkAccess = false
+ ..allowsExpensiveNetworkAccess = false;
+ client = CupertinoClient.fromSessionConfiguration(config);
+} else {
+ client = IOClient(); // Uses an HTTP client based on dart:io
+}
+
+final response = await client.get(Uri.https(
+ 'www.googleapis.com',
+ '/books/v1/volumes',
+ {'q': 'HTTP', 'maxResults': '40', 'printType': 'books'}));
+```
+
+You can also use the [Foundation URL Loading System] API directly.
+
+```dart
+final url = Uri.https(
+ 'www.googleapis.com',
+ '/books/v1/volumes',
+ {'q': 'HTTP', 'maxResults': '40', 'printType': 'books'});
+final session = URLSession.sharedSession();
+final task = session.dataTaskWithCompletionHandler(URLRequest.fromUrl(url),
+ (data, response, error) {
+ if (error == null && response!.statusCode == 200) {
+ print(data!.bytes);
+ }
+});
+task.resume();
+```
+
+[package:http Client]: https://pub.dev/documentation/http/latest/http/Client-class.html
+[Foundation URL Loading System]: https://developer.apple.com/documentation/foundation/url_loading_system
+[dart:io HttpClient]: https://api.dart.dev/stable/dart-io/HttpClient-class.html
