Merge pull request SharePoint#6534 from andrewconnell/spfx-doc-refresh

Refresh & fixedup markdown for Connected APIs section …

Author: andrewconnell

docs/spfx/connect-to-anonymous-apis.md

@@ -1,7 +1,7 @@
 ---
 title: Connect to anonymous APIs
 description: Different approaches of connecting to anonymous APIs from your SharePoint Framework solutions
-ms.date: 10/23/2018
+ms.date: 12/04/2020
 ms.prod: sharepoint
 localization_priority: Priority
 ---
@@ -28,7 +28,9 @@ this.context.httpClient
   });
 ```
 
-Similarly to the SPHttpClient you use for connecting to SharePoint APIs, the HttpClient offers you similar capabilities for performing the most common web requests. If necessary, you can use its options, to configure requests. For example, to specify request headers, you would use the following code:
+Similarly to the **SPHttpClient** you use for connecting to SharePoint APIs, the **HttpClient** offers you similar capabilities for running the most common web requests. If necessary, you can use its options, to configure requests.
+
+For example, to specify request headers, you would use the following code:
 
 ```typescript
 this.context.httpClient
@@ -48,12 +50,12 @@ this.context.httpClient
 
 ### Considerations for using the HttpClient
 
-When using the HttpClient, there are a few things that you should take into account.
+When using the **HttpClient**, there are a few things that you should take into account.
 
 #### Authentication cookies not included
 
-While the HttpClient is very similar to the SPHttpClient, it doesn't include authentication cookies in its requests. So if you were to use it to connect to SharePoint APIs, your requests would fail with a 401 Unauthorized response.
+While the **HttpClient** is similar to the **SPHttpClient**, it doesn't include authentication cookies in its requests. So if you were to use it to connect to SharePoint APIs, your requests would fail with a 401 Unauthorized response.
 
 #### Part of the SharePoint Framework
 
-The HttpClient is part of the SharePoint Framework and you don't need any additional dependencies to start using it. It is already available on the page which is why using it doesn't cause additional performance overhead on runtime.
+The **HttpClient** is part of the SharePoint Framework and you don't need any additional dependencies to start using it. It is already available on the page that is why using it doesn't cause additional performance overhead on runtime.

docs/spfx/connect-to-sharepoint.md

@@ -1,18 +1,18 @@
 ---
 title: Connect to SharePoint APIs
 description: Different approaches of connecting to SharePoint APIs from your SharePoint Framework solutions
-ms.date: 10/19/2020
+ms.date: 12/04/2020
 ms.prod: sharepoint
 localization_priority: Priority
 ---
 
 # Connect to SharePoint APIs
 
-In your SharePoint Framework solutions, you will likely want to interact with data stored in SharePoint. SharePoint offers a rich set of APIs that can be consumed in various ways. This article outlines what options you have, how they work and what their advantages and disadvantages are. 
+In your SharePoint Framework solutions, you'll likely want to interact with data stored in SharePoint. SharePoint offers a rich set of APIs that can be consumed in various ways. This article outlines what options you have, how they work and what their advantages and disadvantages are.
 
 ## Connect to SharePoint API using the SPHttpClient
 
-SharePoint Framework offers the SPHttpClient that you can use to connect to SharePoint REST APIs. A ready-to-use instance of the SPHttpClient is available on the web part/extension context and you can use it to perform all kinds of web request. Following code snippet shows how you would use the SPHttpClient to retrieve the title of the current site:
+SharePoint Framework offers the SPHttpClient that you can use to connect to SharePoint REST APIs. A ready-to-use instance of the SPHttpClient is available on the web part/extension context and you can use it to do all kinds of web request. Following code snippet shows how you would use the SPHttpClient to retrieve the title of the current site:
 
 ```typescript
 this.context.spHttpClient
@@ -25,7 +25,7 @@ this.context.spHttpClient
   });
 ```
 
-The SPHttpClient offers basic functionality for performing the most common web requests. It allows you also, to configure your request by for example specifying request headers. For example, if you wanted to issue a web request without retrieving metadata, you'd use the following code:
+The SPHttpClient offers basic functionality for performing the most common web requests. It allows you also, to configure your request by, for example,  specifying request headers. For example, if you wanted to issue a web request without retrieving metadata, you'd use the following code:
 
 ```typescript
 this.context.spHttpClient
@@ -46,11 +46,11 @@ this.context.spHttpClient
 
 ### Considerations for using the SPHttpClient
 
-When using the SPHttpClient there are a few things that you should take into account.
+When using the SPHttpClient, there are a few things that you should take into account.
 
 #### OData v4.0
 
-By default, the SPHttpClient uses OData v4 specification, which requires using `odata.metadata` instead of just `odata` to control the response metadata. If you use the `odata` directive in OData v4 mode, you will get an error, like: _The HTTP header ACCEPT is missing or its value is invalid._. It is  possible to set the SPHttpClient to OData v3.0 mode, by setting the `odata-version` request header to empty value:
+By default, the SPHttpClient uses OData v4 specification, which requires using `odata.metadata` instead of just `odata` to control the response metadata. If you use the `odata` directive in OData v4 mode, you'll get an error, like: _The HTTP header ACCEPT is missing or its value is invalid._. It is  possible to set the SPHttpClient to OData v3.0 mode, by setting the `odata-version` request header to empty value:
 
 ```typescript
 this.context.spHttpClient
@@ -72,15 +72,15 @@ this.context.spHttpClient
 
 #### Authentication cookies
 
-In the SharePoint Framework there are a number of classes for executing web requests. Two of them are the **SPHttpClient** and **HttpClient**. One of the differences between the SPHttpClient and HttpClient is that the SPHttpClient includes authentication cookies when issuing web requests. Because SharePoint APIs are not anonymous, you need to provide authentication information or you will get an 401 Unauthorized response. Because the HttpClient doesn't include authentication cookies in its request, if you used it to call the SharePoint REST APIs, your requests would fail with a 401 Unauthorized response.
+In the SharePoint Framework, there are a number of classes for executing web requests. Two of them are the **SPHttpClient** and **HttpClient**. One of the differences between the SPHttpClient and HttpClient is that the SPHttpClient includes authentication cookies when issuing web requests. Because SharePoint APIs are not anonymous, you need to provide authentication information or you'll get an 401 Unauthorized response. Because the HttpClient doesn't include authentication cookies in its request, if you used it to call the SharePoint REST APIs, your requests would fail with a 401 Unauthorized response.
 
 #### Part of the SharePoint Framework
 
-The SPHttpClient is part of the SharePoint Framework and you don't need any additional dependencies to start using it. It is already available on the page which is why using it doesn't cause additional performance overhead on runtime.
+The SPHttpClient is part of the SharePoint Framework and you don't need any additional dependencies to start using it. It is already available on the page that is why using it doesn't cause additional performance overhead on runtime.
 
 #### Raw REST queries are error-prone
 
-The SPHttpClient offers basic support for communicating with the SharePoint REST API. If your applications requires more complex GET requests, POST requests or uses more advanced capabilities such as batching, you will quickly notice that using the SPHttpClient is cumbersome and error-prone. In such cases, you should consider using an alternative such as the PnPjs library that offers you a fluent API that can be verified for correctness by TypeScript.
+The SPHttpClient offers basic support for communicating with the SharePoint REST API. If your applications require more complex GET requests, POST requests or uses more advanced capabilities such as batching, you'll quickly notice that using the SPHttpClient is cumbersome and error-prone. In such cases, you should consider using an alternative such as the PnPjs library that offers you a fluent API that can be verified for correctness by TypeScript.
 
 ## Connect to SharePoint using PnPjs
 
@@ -97,26 +97,26 @@ sp.web
 
 [!INCLUDE [pnp-js](../../includes/snippets/open-source/pnp-js.md)]
 
-Notice, how less verbose the code is comparing to the SharePoint Framework SPHttpClient and how all elements of the requests, except for the names of the properties to retrieve, are strongly-typed lowering the risk of runtime errors.
+Notice, how less verbose the code is comparing to the SharePoint Framework SPHttpClient and how all elements of the requests, except for the names of the properties to retrieve, are strongly typed lowering the risk of runtime errors.
 
-For more information about how to setup and use PnPjs in the SharePoint Framework see the PnPjs documentation at [https://pnp.github.io/pnpjs/](https://pnp.github.io/pnpjs/).
+For more information about how to setup and use PnPjs in the SharePoint Framework, see the PnPjs documentation at [https://pnp.github.io/pnpjs/](https://pnp.github.io/pnpjs/).
 
 ### Considerations for using PnPjs
 
 When deciding whether you should use PnPjs or not, following are a few considerations that you should take into account.
 
 #### Raw REST queries are error prone
 
-Issuing raw REST requests using the SPHttpClient is error-prone. Especially, when your application will need to execute POST queries or you will want to use some of the more advanced capabilities such as request batching, composing the correct requests and parsing the responses will be cumbersome. Not to mention, the only way to verify if the requests are correct is by running the code in the browser. With PnPjs you can communicate with SharePoint APIs in a type-safe way and easily use the advanced capabilities of SharePoint API what allows you to focus on building your application instead of testing its requests.
+Issuing raw REST requests using the SPHttpClient is error-prone. Especially, when your application will need to execute POST queries or you'll want to use some of the more advanced capabilities such as request batching, composing the correct requests and parsing the responses will be cumbersome. Not to mention, the only way to verify if the requests are correct is by running the code in the browser. With PnPjs, you can communicate with SharePoint APIs in a type-safe way and easily use the advanced capabilities of SharePoint API what allows you to focus on building your application instead of testing its requests.
 
 #### Open-source project
 
-PnPjs is an open-source project managed by the SharePoint community. There is no SLA for using PnPjs in your solutions and Microsoft support won't assist you with any possible issues when caused by PnPjs. That said, PnPjs is actively developed and the community quickly responds to all submitted issues and questions.
+PnPjs is an open-source project managed by the SharePoint community. There's no SLA for using PnPjs in your solutions and Microsoft support won't assist you with any possible issues when caused by PnPjs. That said, PnPjs is actively developed and the community quickly responds to all submitted issues and questions.
 
 #### Additional dependency
 
-PnPjs is an additional dependency that you need to add to your project and manage over time. You need to keep track of its updates and upgrade your project when necessary. The community behind PnPjs regularly communicates the state of the current work, upcoming releases and the impact, if any, of upgrading to the newer version.
+PnPjs is an additional dependency that you need to add to your project and manage over time. You need to keep track of its updates and upgrade your project when necessary. The community behind PnPjs regularly communicates the state of the current work, upcoming releases, and the impact, if any, of upgrading to the newer version.
 
 #### Additional payload
 
-PnPjs offers a rich set of capabilities for communicating with SharePoint APIs. But these capabilities add extra load to your project. Compressed, PnPjs will add ~40KB to the generated bundle size.
+PnPjs offers a rich set of capabilities for communicating with SharePoint APIs. But these capabilities add extra load to your project. Compressed, PnPjs will add ~40 KB to the generated bundle size.

docs/spfx/subscribe-to-list-notifications.md

@@ -1,26 +1,26 @@
 ---
 title: Subscribe to list notifications
 description: Get notified and respond to changes to files in SharePoint Document Libraries
-ms.date: 12/10/2019
+ms.date: 12/04/2020
 ms.prod: sharepoint
 localization_priority: Normal
 ---
 
 # Subscribe to list notifications
 
-Starting from SharePoint Framework v1.7.0, you can subscribe to changes to files stored in a SharePoint Document Library. This allows you to respond to changes when they happen, without having to regularly poll the contents of the library.
+Introduced in SharePoint Framework v1.7.0, you can subscribe to changes to files stored in a SharePoint Document Library. This allows you to respond to changes when they happen, without having to regularly poll the contents of the library.
 
 ## Prerequisites
 
-To use the SharePoint Framework list subscription capability, you first need to install the `@microsoft/sp-list-subscription` npm package. You can do it using the following code snippet:
+To use the SharePoint Framework list subscription capability, you first need to install the **@microsoft/sp-list-subscription** npm package. You can do it using the following code snippet:
 
-```sh
+```console
 npm install @microsoft/sp-list-subscription --save --save-exact
 ```
 
 ## Get notified of changes to documents stored in a SharePoint Document Library
 
-To subscribe to changes to files stored in a SharePoint Document Library, create an instance of the `ListSubscriptionFactory` class. Next, call the `createSubscription` method passing the ID of the Document Library to which you want to subscribe. If the Document Library is located in the current site, it's sufficient to specify just the library ID. If it's located in a different site or site collection, then you need to specify their ID's as well.
+To subscribe to changes to files stored in a SharePoint Document Library, create an instance of the `ListSubscriptionFactory` class. Next, call the `createSubscription()` method passing the ID of the Document Library to which you want to subscribe. If the Document Library is located in the current site, it's sufficient to specify just the library ID. If it's located in a different site or site collection, then you need to specify their IDs as well.
 
 Following, is an example of a list subscription for a Document Library located in the current site:
 
@@ -72,11 +72,11 @@ this._listSubscriptionFactory.createSubscription({
 });
 ```
 
-### Get notified when the subscription has been established or cancelled
+### Get notified when the subscription has been established or canceled
 
 In some cases, you might want to get notified when the component that you're building successfully subscribed to list notifications or if the connection has been broken. This would allow you to communicate the connection to the user through the UI.
 
-The list subscription API, exposes two additional callbacks which you can implement to respond to the subscription status. The following code illustrates the case, where the component will be notified when the subscription has been established and when it was disconnected.
+The list subscription API, exposes two additional callbacks that you can implement to respond to the subscription status. The following code illustrates the case, where the component will be notified when the subscription has been established and when it was disconnected.
 
 ```typescript
 private createListSubscription(): void {
@@ -108,7 +108,7 @@ The method for the `callbacks.disconnect` callback passes as an argument the rea
 
 - all SharePoint Framework components can use the list subscription capabilities
 - you can subscribe to events from libraries (but not lists)
-- there is a few seconds delay between the change and the notification being received by the component
+- there's a few seconds delay between the change and the notification being received by the component
 - components can subscribe to changes in multiple Document Libraries
 - the change notification doesn't pass any information about the added or changed document. To see what has changed, use the SharePoint REST API or Microsoft Graph