diff --git a/examples/misc/lib/library_tour/async/basic.dart b/examples/misc/lib/library_tour/async/basic.dart index cb44c13519..9420d46277 100644 --- a/examples/misc/lib/library_tour/async/basic.dart +++ b/examples/misc/lib/library_tour/async/basic.dart @@ -1,11 +1,12 @@ -import 'dart:html'; +import 'package:http/http.dart'; void miscDeclAnalyzedButNotTested() { - const url = 'humans.txt'; + final url = Uri.parse('humans.txt'); + final httpClient = Client(); { // #docregion then - HttpRequest.getString(url).then((String result) { + httpClient.read(url).then((String result) { print(result); }); // #enddocregion then @@ -13,7 +14,7 @@ void miscDeclAnalyzedButNotTested() { { // #docregion catchError - HttpRequest.getString(url).then((String result) { + httpClient.read(url).then((String result) { print(result); }).catchError((e) { // Handle or ignore the error. diff --git a/examples/misc/pubspec.yaml b/examples/misc/pubspec.yaml index 2287dc0431..1c5494ea3a 100644 --- a/examples/misc/pubspec.yaml +++ b/examples/misc/pubspec.yaml @@ -8,6 +8,7 @@ dependencies: args: ^2.4.2 characters: ^1.3.0 examples_util: { path: ../util } + http: ^1.1.2 dev_dependencies: lints: ^3.0.0 diff --git a/src/guides/libraries/_dart-html-tour.md b/src/guides/libraries/_dart-html-tour.md index b482e9d8c7..83cb92a6da 100644 --- a/src/guides/libraries/_dart-html-tour.md +++ b/src/guides/libraries/_dart-html-tour.md @@ -322,119 +322,15 @@ subclasses. Some common events include: ### Using HTTP resources with HttpRequest -Formerly known as XMLHttpRequest, the [HttpRequest][] class -gives you access to HTTP resources from within your browser-based app. -Traditionally, AJAX-style apps make heavy use of HttpRequest. Use -HttpRequest to dynamically load JSON data or any other resource from a -web server. You can also dynamically send data to a web server. - - -#### Getting data from the server - -The HttpRequest static method `getString()` is an easy way to get data -from a web server. Use `await` with the `getString()` call -to ensure that you have the data before continuing execution. - - -{% prettify dart tag=pre+code %} -void main() async { - String pageHtml = [!await HttpRequest.getString(url);!] - // Do something with pageHtml... -} -{% endprettify %} - -Use try-catch to specify an error handler: - - -```dart -try { - var data = await HttpRequest.getString(jsonUri); - // Process data... -} catch (e) { - // Handle exception... -} -``` - -If you need access to the HttpRequest, not just the text data it -retrieves, you can use the `request()` static method instead of -`getString()`. Here's an example of reading XML data: - - -```dart -void main() async { - HttpRequest req = await HttpRequest.request( - url, - method: 'HEAD', - ); - if (req.status == 200) { - // Successful URL access... - } - // ··· -} -``` - -You can also use the full API to handle more interesting cases. For -example, you can set arbitrary headers. - -The general flow for using the full API of HttpRequest is as follows: - -1. Create the HttpRequest object. -2. Open the URL with either `GET` or `POST`. -3. Attach event handlers. -4. Send the request. - -For example: - - -```dart -var request = HttpRequest(); -request - ..open('POST', url) - ..onLoadEnd.listen((e) => requestComplete(request)) - ..send(encodedData); -``` - -#### Sending data to the server - -HttpRequest can send data to the server using the HTTP method POST. For -example, you might want to dynamically submit data to a form handler. -Sending JSON data to a RESTful web service is another common example. - -Submitting data to a form handler requires you to provide name-value -pairs as URI-encoded strings. (Information about the URI class is in -the [URIs section][URIs] of the [Dart Library Tour.][Dart Library Tour]) -You must also set the `Content-type` header to -`application/x-www-form-urlencoded` if you wish to send data to a form -handler. - - -```dart -String encodeMap(Map data) => data.entries - .map((e) => - '${Uri.encodeComponent(e.key)}=${Uri.encodeComponent(e.value)}') - .join('&'); - -void main() async { - const data = {'dart': 'fun', 'angular': 'productive'}; - - var request = HttpRequest(); - request - ..open('POST', url) - ..setRequestHeader( - 'Content-type', - 'application/x-www-form-urlencoded', - ) - ..send(encodeMap(data)); - - await request.onLoadEnd.first; - - if (request.status == 200) { - // Successful URL access... - } - // ··· -} -``` +You should avoid directly using `dart:html` to make HTTP requests. +The [`HttpRequest`][] class in `dart:html` is platform-dependent +and tied to a single implementation. +Instead, use a higher-level library like +[`package:http`]({{site.pub-pkg}}/http). +The [Fetch data from the internet][] tutorial +explains how to make HTTP requests +using `package:http`. ### Sending and receiving real-time data with WebSockets @@ -542,9 +438,10 @@ For more information about Dart web libraries, see the [AnchorElement]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/AnchorElement-class.html [dart:html]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/dart-html-library.html [Dart Library Tour]: /guides/libraries/library-tour +[Fetch data from the internet]: /tutorials/server/fetch-data [Document]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Document-class.html [Element]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Element-class.html -[HttpRequest]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/HttpRequest-class.html +[`HttpRequest`]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/HttpRequest-class.html [IndexedDB]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-indexed_db/dart-indexed_db-library.html [MessageEvent]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/MessageEvent-class.html [Nodes]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/Node-class.html diff --git a/src/guides/libraries/_dart-io-tour.md b/src/guides/libraries/_dart-io-tour.md index 03cdb7246b..f9ef68e550 100644 --- a/src/guides/libraries/_dart-io-tour.md +++ b/src/guides/libraries/_dart-io-tour.md @@ -234,27 +234,15 @@ void processRequest(HttpRequest request) { #### HTTP client -The [HttpClient][] class -helps you connect to HTTP resources from your Dart command-line or -server-side application. You can set headers, use HTTP methods, and read -and write data. The HttpClient class does not work in browser-based -apps. When programming in the browser, use the -[dart:html HttpRequest class.][HttpRequest] -Here's an example of using HttpClient: - - -```dart -void main() async { - var url = Uri.parse('http://localhost:8888/dart'); - var httpClient = HttpClient(); - var request = await httpClient.getUrl(url); - var response = await request.close(); - var data = await utf8.decoder.bind(response).toList(); - print('Response ${response.statusCode}: $data'); - httpClient.close(); -} -``` +You should avoid directly using `dart:io` to make HTTP requests. +The [HttpClient][] class in `dart:io` is platform-dependent +and tied to a single implementation. +Instead, use a higher-level library like +[`package:http`]({{site.pub-pkg}}/http). +The [Fetch data from the internet][] tutorial +explains how to make HTTP requests +using `package:http`. ### More information @@ -269,6 +257,7 @@ For more information about server-side and command-line app development, see the [library tour]: /guides/libraries/library-tour [dart:io]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-io/dart-io-library.html [Directory]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-io/Directory-class.html +[Fetch data from the internet]: /tutorials/server/fetch-data [File]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-io/File-class.html [HttpClient]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-io/HttpClient-class.html [HttpRequest]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html/HttpRequest-class.html diff --git a/src/guides/libraries/library-tour.md b/src/guides/libraries/library-tour.md index 5522af5fbf..4af7d76922 100644 --- a/src/guides/libraries/library-tour.md +++ b/src/guides/libraries/library-tour.md @@ -1196,13 +1196,13 @@ see the [asynchronous programming codelab](/codelabs/async-await). {% endcomment %} You can use `then()` to schedule code that runs when the future completes. For -example, `HttpRequest.getString()` returns a Future, since HTTP requests +example, [`Client.read()`][] returns a Future, since HTTP requests can take a while. Using `then()` lets you run some code when that Future has completed and the promised string value is available: ```dart -HttpRequest.getString(url).then((String result) { +httpClient.read(url).then((String result) { print(result); }); ``` @@ -1212,7 +1212,7 @@ object might throw. ```dart -HttpRequest.getString(url).then((String result) { +httpClient.read(url).then((String result) { print(result); }).catchError((e) { // Handle or ignore the error. @@ -1806,6 +1806,7 @@ To learn more about the Dart language, see the [ArgumentError]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/ArgumentError-class.html [Assert]: /language/error-handling#assert +[`Client.read()`]: {{site.pub-api}}/http/latest/http/Client/read.html [Comparable]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/Comparable-class.html [Dart API]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}} [DateTime]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-core/DateTime-class.html diff --git a/src/tutorials/server/fetch-data.md b/src/tutorials/server/fetch-data.md index 386aead3ca..9c4cfb235b 100644 --- a/src/tutorials/server/fetch-data.md +++ b/src/tutorials/server/fetch-data.md @@ -129,12 +129,17 @@ see [What is a URL?][] on the mdn web docs. ## Retrieve the necessary dependencies -You can directly use `dart:io` or `dart:html` to make HTTP requests, -however those libraries are platform dependent. -`package:http` provides a cross-platform library +The `package:http` library provides a cross-platform solution for making composable HTTP requests, with optional fine-grained control. +{{site.alert.note}} + You should avoid directly using `dart:io` or `dart:html` + to make HTTP requests. + Those libraries are platform-dependent + and tied to a single implementation. +{{site.alert.end}} + To add a dependency on `package:http`, run the following [`dart pub add`][] command from the top of your repo: @@ -230,7 +235,7 @@ which can also be seen in your browser at ```json { "name": "http", - "latestVersion": "0.13.5", + "latestVersion": "1.1.2", "description": "A composable, multi-platform, Future-based API for HTTP requests.", "publisher": "dart.dev", "repository": "https://github.com/dart-lang/http"