docs(toh-6): getHero makes HTTP get-by-id request (#2906)

Author: wardbell

public/docs/_examples/toh-6/ts/app/hero.service.ts

@@ -35,10 +35,16 @@ export class HeroService {
   }
 
   // #enddocregion getHeroes
+
+  // #docregion getHero
   getHero(id: number): Promise<Hero> {
-    return this.getHeroes()
-               .then(heroes => heroes.find(hero => hero.id === id));
+    const url = `${this.heroesUrl}/${id}`;
+    return this.http.get(url)
+      .toPromise()
+      .then(response => response.json().data as Hero)
+      .catch(this.handleError);
   }
+  // #enddocregion getHero
 
   // #docregion delete
   delete(id: number): Promise<void> {

public/docs/ts/latest/tutorial/toh-pt6.jade

@@ -212,12 +212,32 @@ block get-heroes-details
   We've also decided to return a user friendly form of the error to
   the caller in a !{rejected_promise} so that the caller can display a proper error message to the user.
 
-  ### Unchanged `getHeroes` API
+  ### Get hero by id
+  The `HeroDetailComponent` asks the `HeroService` to fetch a single hero to edit.
+  
+  The `HeroService` currently fetches all heroes and then finds the desired hero 
+  by filtering for the one with the matching `id`.
+  That's fine in a simulation. It's wasteful to ask a real server for _all_ heroes when we only want one.
+  Most web APIs support a _get-by-id_ request in the form `api/hero/:id` (e.g., `api/hero/11`).
 
-  Although we made significant *internal* changes to `getHeroes()`, the public signature did not change.
-  We still return a !{_Promise}. We won't have to update any of the components that call `getHeroes()`.
+  Update the `HeroService.getHero` method to make a _get-by-id_ request,
+  applying what we just learned to write `getHeroes`:
++makeExcerpt('app/hero.service.ts', 'getHero', '')
+:marked
+  It's almost the same as `getHeroes`. 
+  The URL identifies _which_ hero the server should update by encoding the hero id into the URL
+  to match the `api/hero/:id` pattern.
+
+  We also adjust to the fact that the `data` in the response is a single hero object rather than array.
+
+  ### Unchanged _getHeroes_ API
+
+  Although we made significant *internal* changes to `getHeroes()` and `getHero()`, 
+  the public signatures did not change.
+  We still return a !{_Promise} from both methods. 
+  We won't have to update any of the components that call them.
 
-  Our stakeholders are thrilled with the added flexibility from the API integration.
+  Our stakeholders are thrilled with the web API integration so far.
   Now they want the ability to create and delete heroes.
 
   Let's see first what happens when we try to update a hero's details.
@@ -230,15 +250,12 @@ block get-heroes-details
   it. As we type, the hero name is updated in the view heading.
   But when we hit the `Back` button, the changes are lost!
 
-.l-sub-section
-  :marked
-    Updates weren't lost before, what's happening?
-    When the app used a list of mock heroes, changes were made directly to the
-    hero objects in the single, app-wide shared list. Now that we are fetching data
-    from a server, if we want changes to persist, we'll need to write them back to
-    the server.
+  Updates weren't lost before. What changed?
+  When the app used a list of mock heroes, updates were applied directly to the
+  hero objects within the single, app-wide, shared list. Now that we are fetching data
+  from a server, if we want changes to persist, we'll need to write them back to
+  the server.
 
-:marked
   ### Save hero details
 
   Let's ensure that edits to a hero's name aren't lost. Start by adding,