Networking Guide

docs/Basics-Network.md

@@ -1,25 +1,27 @@
 ---
 id: basics-network
-title: Network
+title: Networking
 layout: docs
 category: The Basics
 permalink: docs/network.html
 next: more-resources
 ---
 
-One of React Native's goals is to be a playground where we can experiment with different architectures and crazy ideas. Since browsers are not flexible enough, we had no choice but to reimplement the entire stack. In the places that we did not intend to change anything, we tried to be as faithful as possible to the browser APIs. The networking stack is a great example.
+Many modern mobile apps will at some point find the need to load resources from a remote endpoint. You may want to make a POST request to a REST API, or you may simply need to fetch a chunk of static content from another server.
 
-## Fetch
+React Native provides the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) for your networking needs.
 
-[fetch](https://fetch.spec.whatwg.org/) is a better networking API being worked on by the standards committee and is already available in Chrome. It is available in React Native by default.
+## Using Fetch
 
-#### Usage
+Fetch will seem familiar if you have used `XMLHttpRequest` or other networking APIs before. You may refer to MDN's guide on [Using Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) for additional information.
+
+In order to fetch content from an arbitrary endpoint, just pass the URL to fetch:
 
 ```js
 fetch('https://mywebsite.com/endpoint/')
 ```
 
-Include a request object as the optional second argument to customize the HTTP request:
+Fetch also takes an optional second argument that allows you to customize the HTTP request. You may want to specify additional headers, or make a POST request:
 
 ```js
 fetch('https://mywebsite.com/endpoint/', {
@@ -35,121 +37,47 @@ fetch('https://mywebsite.com/endpoint/', {
 })
 ```
 
-#### Async
+Take a look at the [Fetch Request docs](https://developer.mozilla.org/en-US/docs/Web/API/Request) for a full list of properties.
 
-`fetch` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that can be processed in two ways:
+### Handling the response
 
-1.  Using `then` and `catch` in synchronous code:
+The above examples show how you can make a request. In many cases, you will want to do something with the response.
 
-  ```js
-  fetch('https://mywebsite.com/endpoint.php')
-    .then((response) => response.text())
-    .then((responseText) => {
-      console.log(responseText);
-    })
-    .catch((error) => {
-      console.warn(error);
-    });
-  ```
-2.  Called within an asynchronous function using ES7 `async`/`await` syntax:
+Networking is an inherently asynchronous operation. Fetch methods will return a  [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that make it straightforward to write code that works in an asynchronous manner:
 
   ```js
-  class MyComponent extends React.Component {
-    ...
-    async getUsersFromApi() {
-      try {
-        let response = await fetch('https://mywebsite.com/endpoint/');
-        let responseJson = await response.json();
-        return responseJson.users;
-      } catch(error) {
-        // Handle error
+  getMoviesFromApiAsync() {
+    return fetch('http://facebook.github.io/react-native/movies.json')
+      .then((response) => response.json())
+      .then((responseJson) => {
+        return responseJson.movies;
+      })
+      .catch((error) => {
         console.error(error);
-      }
-    }
-    ...
+      });
   }
   ```
 
-- Note: Errors thrown by rejected Promises need to be caught, or they will be swallowed silently
-
-## WebSocket
-
-WebSocket is a protocol providing full-duplex communication channels over a single TCP connection.
-
-```js
-var ws = new WebSocket('ws://host.com/path');
-
-ws.onopen = () => {
-  // connection opened
-  ws.send('something');
-};
-
-ws.onmessage = (e) => {
-  // a message was received
-  console.log(e.data);
-};
-
-ws.onerror = (e) => {
-  // an error occurred
-  console.log(e.message);
-};
-
-ws.onclose = (e) => {
-  // connection closed
-  console.log(e.code, e.reason);
-};
-```
-
-## XMLHttpRequest
-
-XMLHttpRequest API is implemented on-top of [iOS networking apis](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/URLLoadingSystem/URLLoadingSystem.html) and [OkHttp](http://square.github.io/okhttp/). The notable difference from web is the security model: you can read from arbitrary websites on the internet since there is no concept of [CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
+You can also use ES7's `async`/`await` syntax in React Native app:
 
-```js
-var request = new XMLHttpRequest();
-request.onreadystatechange = (e) => {
-  if (request.readyState !== 4) {
-    return;
-  }
-
-  if (request.status === 200) {
-    console.log('success', request.responseText);
-  } else {
-    console.warn('error');
+  ```js
+  async getMoviesFromApi() {
+    try {
+      let response = await fetch('http://facebook.github.io/react-native/movies.json');
+      let responseJson = await response.json();
+      return responseJson.movies;
+    } catch(error) {
+      console.error(error);
+    }
   }
-};
-
-request.open('GET', 'https://mywebsite.com/endpoint.php');
-request.send();
-```
+  ```
 
-You can also use -
+Don't forget to catch any errors that may be thrown by `fetch`, otherwise they will be dropped silently.
 
-```js
-var request = new XMLHttpRequest();
-
-function onLoad() {
-    console.log(request.status);
-    console.log(request.responseText);
-};
-
-function onTimeout() {
-    console.log('Timeout');
-    console.log(request.responseText);
-};
-
-function onError() {
-    console.log('General network error');
-    console.log(request.responseText);
-};
-
-request.onload = onLoad;
-request.ontimeout = onTimeout;
-request.onerror = onError;
-request.open('GET', 'https://mywebsite.com/endpoint.php');
-request.send();
-```
+## WebSocket Support
 
+React Native supports [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket), a protocol which provides full-duplex communication channels over a single TCP connection.
 
-Please follow the [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) for a complete description of the API.
+## Using Other Networking Libraries
 
-As a developer, you're probably not going to use XMLHttpRequest directly as its API is very tedious to work with. But the fact that it is implemented and compatible with the browser API gives you the ability to use third-party libraries such as [frisbee](https://github.com/niftylettuce/frisbee) or [axios](https://github.com/mzabriskie/axios) directly from npm.
+The `XMLHttpRequest` API, used by many networking libraries, is built in to React Native. This means that you can use third party libraries such as [frisbee](https://github.com/niftylettuce/frisbee) or [axios](https://github.com/mzabriskie/axios) if you prefer.

website/src/react-native/movies.json

@@ -0,0 +1,11 @@
+{
+  "title": "The Basics - Networking",
+  "description": "Your app fetched this from a remote endpoint!",
+  "movies": [
+    { "title": "Star Wars", "releaseYear": "1977"},
+    { "title": "Back to the Future", "releaseYear": "1985"},
+    { "title": "The Matrix", "releaseYear": "1999"},
+    { "title": "Inception", "releaseYear": "2010"},
+    { "title": "Interstellar", "releaseYear": "2014"}
+  ]
+}