SharePoint APIs edit pass (SharePoint#1338)

* Edit in progress

* Edit in progress

* Edit in progress

* Edit in progress

* Adjusted spacing in tables

Author: Linda-Editor

docs/apis/alm-api-for-spfx-add-ins.md

@@ -1,36 +1,37 @@
 ---
 title:  Application Lifecycle Management (ALM) APIs 
-ms.date: 12/19/2017
+description: ALM APIs provide simple APIs to manage deployment of your SharePoint Framework solutions and add-ins across your tenant.
+ms.date: 02/08/2018
 ms.prod: sharepoint
 ms.assetid: fdf7ecb2-8851-425b-b058-3285fba77b68
 ---
 
 # Application Lifecycle Management (ALM) APIs  
 
-ALM APIs are providing simple APIs to manage deployment of your SharePoint Framework solutions and add-ins cross your tenant. ALM APIs support following capabilities.
+ALM APIs provide simple APIs to manage deployment of your SharePoint Framework solutions and add-ins across your tenant. ALM APIs support the following capabilities:
 
-- Add SharePoint Framework solution or SharePoint add-in to tenant app catalog
-- Enable SharePoint Framework solution or SharePoint add-in to be available for installation in tenant app catalog
-- Disable SharePoint Framework solution or SharePoint add-in not to be available for installation in tenant app catalog
-- Install SharePoint Framework solution or SharePoint add-in from tenant app catalog to a site
-- Upgrade SharePoint Framework solution or SharePoint add-in to a site, which has a newer version available in the tenant app catalog
-- Uninstall SharePoint Framework solution or SharePoint add-in from the site
+- Add SharePoint Framework solution or SharePoint Add-in to tenant App Catalog.
+- Enable SharePoint Framework solution or SharePoint Add-in to be available for installation in tenant App Catalog.
+- Disable SharePoint Framework solution or SharePoint Add-in not to be available for installation in tenant App Catalog.
+- Install SharePoint Framework solution or SharePoint Add-in from tenant App Catalog to a site.
+- Upgrade SharePoint Framework solution or SharePoint Add-in to a site, which has a newer version available in the tenant App Catalog.
+- Uninstall SharePoint Framework solution or SharePoint Add-in from the site.
 
-ALM APIs can be used to perform exactly the same operations which are available from UI perspective. When these APIs are used, all typical actions will be performed. Here are some of the characteristics for ALM APIs.
+ALM APIs can be used to perform exactly the same operations that are available from a UI perspective. When these APIs are used, all typical actions are performed. Following are some of the characteristics of ALM APIs:
 
-- Install and UnInstall events are being fired for provider hosted add-ins when corresponding operations are occurred
-- ALM APIs supports app-only based operations
+- `Install` and `UnInstall` events are being fired for provider-hosted add-ins when corresponding operations occur.
+- ALM APIs support app-only-based operations.
 
-ALM APIs are natively provided using REST APIs, but there is also additional CSOM extensions and PowerShell commandlets available through SharePoint Patterns and Practices.
+ALM APIs are natively provided by using REST APIs, but there are also additional CSOM extensions and PowerShell cmdlets available through SharePoint Patterns and Practices.
 
 > [!NOTE] 
-> ALM APIs are not currently supported for [site collection app catalog](../general-development/site-collection-app-catalog.md). Support will be added early 2018.
+> ALM APIs are not currently supported for the [site collection App Catalog](../general-development/site-collection-app-catalog.md). Support will be added in early 2018.
 
 ## REST API
 
-### Add solution package to tenant app catalog 
+### Add solution packages to the tenant App Catalog 
 
-Adding solution to the tenant app catalog. This API is designed to be executed in the context of the tenant app catalog site.
+This API is designed to be executed in the context of the tenant App Catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/Add(overwrite=true, url='test.txt')
@@ -39,148 +40,156 @@ binaryStringRequestBody: true
 body: 'byte array of the file'
 ```
 
-### Deploy solution package in tenant app catalog
+### Deploy solution packages in the tenant App Catalog
 
-Enable solution to be available to install to specific sites. This API is designed to be executed in the context of the tenant app catalog site.
+This enables the solution to be available to install to specific sites. This API is designed to be executed in the context of the tenant App Catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Deploy
 ```
 
 > [!NOTE]
-> This operation is required to be completed after add, before you can install packages to specific sites. 
+> This operation is required to be completed after Add before you can install packages to specific sites. 
 
-### Retract solution package in the tenant app catalog
+### Retract solution packages in the tenant App Catalog
 
-Retract solution to be available from the sites. This API is designed to be executed in the context of the tenant app catalog site.
+This retracts the solution to be available from the sites. This API is designed to be executed in the context of the tenant App Catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Retract
 ```
 
 > [!NOTE]
-> If you run this operation after you have already installed solutions to site, they will stop working since solution is disabled from the tenant level.
+> If you run this operation after you have installed solutions to the site, they will stop working because the solution is disabled from the tenant level.
 
-### Remove solution package from tenant app catalog
+### Remove solution packages from the tenant App Catalog
 
-Remove the solution package from the tenant app catalog. This API is designed to be executed in the context of the tenant app catalog site.
+This API is designed to be executed in the context of the tenant App Catalog site.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Remove
 ```
 
 > [!NOTE]
-> Solution will be also automatically retracted, if that operation has not performed before Remove operation.
+> If the Retract operation is not performed before the Remove operation, the solution is automatically retracted.
 
-### List available packages from tenant app catalog
+### List available packages from the tenant App Catalog
 
-REST API for getting list of available SharePoint Framework solutions or add-ins in tenant app catalog.
+Use this REST API for getting a list of available SharePoint Framework solutions or add-ins in the tenant App Catalog.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps
 method: GET
 ```
 
-### Details on individual solution package from tenant app catalog
+### Details about individual solution packages in the tenant App Catalog
 
-REST API for getting details on individual SharePoint Framework solution or add-in available in the tenant app catalog.
+Use this REST API for getting details about individual SharePoint Framework solutions or add-ins available in the tenant App Catalog.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')
 method: GET
 ```
 
-### Install solution package from tenant app catalog to SharePoint site
+### Install solution package from the tenant App Catalog to a SharePoint site
 
-Install a solution package with specific identifier from tenant app catalog to the site based on URL context. This REST call can be executed in the context of the site where the install operation should happen.
+Install a solution package with a specific identifier from the tenant App Catalog to the site based on URL context. This REST call can be executed in the context of the site where the install operation should happen.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Install
 method: POST
 ```
 
-### Upgrade solution package in SharePoint site
+### Upgrade solution packages on the SharePoint site
 
-Upgrade a solution package from the site to a newer version available in the tenant app catalog. This REST call can be executed in the context of the site where the upgrade operation should happen.
+Upgrade a solution package from the site to a newer version available in the tenant App Catalog. This REST call can be executed in the context of the site where the upgrade operation should happen.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Upgrade
 method: POST
 ```
 
-### Uninstall solution package from SharePoint site
+### Uninstall solution packages from the SharePoint site
 
-Uninstall a solution package from the site. This REST call can be executed in the context of the site where the uninstall operation should happen.
+This REST call can be executed in the context of the site where the uninstall operation should happen.
 
 ```
 url: /_api/web/tenantappcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Uninstall
 method: POST
 ```
 > [!NOTE]
-> When you use the REST API to uninstall solution package from the site, it is not relocated to the recycle bin.
+> When you use the REST API to uninstall a solution package from the site, it is not relocated to the recycle bin.
 
 
-## SharePoint PnP PowerShell cmdlets to programmatically add and deploy SharePoint Apps
+## SharePoint PnP PowerShell cmdlets 
 
-Using [PnP PowerShell](https://msdn.microsoft.com/en-us/pnp_powershell/pnp-powershell-overview) you can automate the deployment, publishing, installing, upgrading and retracting your apps. Checkout below chapter to learn more about this cmdlets.
+By using [PnP PowerShell](https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sharepoint-ps), you can automate deploying, publishing, installing, upgrading, and retracting your apps. 
 
-### Adding and publishing your app to the app catalog
-Adding your app (.sppkg file, .app file) to the tenant app catalog is a per-requisite to later on make your app available for use in your SharePoint sites. Doing so can be done using below simple cmdlet:
+### Add and publish your app to the App Catalog
+
+Adding your app (.sppkg file, .app file) to the tenant App Catalog is a prerequisite to making your app available for use on your SharePoint sites. You can do so by using the following cmdlet:
 
 ```PowerShell
 Add-PnPApp -Path ./myapp.sppkg
 ```
 
-Once added you'll need to continue with publishing your app, effectively making the app available to be used by the users of your tenant. Below PnP PowerShell cmdlets shows how this can be done:
+After you add it, you need to continue with publishing your app, effectively making the app available to the users of your tenant. The following PnP PowerShell cmdlet shows how this can be done:
 
 ```PowerShell
 Publish-PnPApp -Identity <app id> -SkipFeatureDeployment
 ```
 
 
 > [!NOTE]
-> Use the SkipFeatureDeployment flag to allow an app that was developed for tenant wide deployment to be actually available as a tenant wide deployed app.
+> Use the `SkipFeatureDeployment` flag to allow an app that was developed for tenant-wide deployment to be actually available as a tenant-wide deployed app.
+
 
 
+### Remove the app from the App Catalog
 
-### Removing the app from the app catalog
-Obviously you might also want to remove an earlier added app and that can be done using the following cmdlet:
+To remove an app added earlier, use the following cmdlet:
 
 ```PowerShell
 Remove-PnPApp -Identity <app id>
 ```
 
 
-### Using apps on your site
-Once the app was added to the app catalog and published you can continue with installing the app to your site.
+### Use apps on your site
+
+After the app is added to the App Catalog and published, you can install the app to your site:
 
 ```PowerShell
 Install-PnPApp -Identity <app id>
 ```
 
 
-An added app also needs be upgraded:
+To upgrade the app:
 
 ```PowerShell
 Update-PnPApp -Identity <app id>
 ```
 
 
-And you off course also uninstall the app again from your site:
+To uninstall the app from your site:
 
 ```PowerShell
 Uninstall-PnPApp -Identity <app id>
 ```
 
 
 > [!NOTE]
-> When you uninstall an app from your site the app is completely deleted, so it will not end up in the site's recycle bin.
+> When you uninstall an app from your site, the app is completely deleted, so it does not end up in the site's recycle bin.
 
 
 
-### Knowing which apps are there for you to use
-Getting a list of apps that can be added to the site is possible using:
+### Know which apps are there for you to use
+
+You can get a list of apps that can be added to the site by using:
 
 ```PowerShell
 Get-PnPApp
 ```
+
+## See also
+
+- [Get to know the SharePoint REST service](../sp-add-ins/get-to-know-the-sharepoint-rest-service.md)

docs/apis/communication-site-creation-rest.md

@@ -1,22 +1,30 @@
-# Creating SharePoint Communication Site using REST
+---
+title: Create SharePoint Communication site using REST
+description: Create and get the status of a new modern SharePoint Communication site by using the REST interface.
+ms.date: 02/08/2018
+ms.prod: sharepoint
+---
 
-Learn how to create and get the status of a new modern SharePoint Communication site with the REST interface.
+# Create SharePoint Communication site using REST
 
-## Prerequisites
+This topic assumes that you are already familiar with the following topics:
 
-This topic assumes that you are already familiar with the topics Get to know the SharePoint REST service and Complete basic operations using SharePoint REST endpoints. It does not provide code snippets.
+- [Get to know the SharePoint REST service](../sp-add-ins/get-to-know-the-sharepoint-rest-service.md)
+- [Complete basic operations using SharePoint REST endpoints](../sp-add-ins/complete-basic-operations-using-sharepoint-rest-endpoints.md)
 
-The following REST commands are available for creating a modern SharePoint Communication site.
+This topic does not provide code snippets.
 
-- **Create** - Create a new SharePoint Communication site
-- **Status** - Get the status of a SharePoint Communication site 
+The following REST commands are available for creating a modern SharePoint Communication site:
 
-The URL for communication site REST commands is based on `_api/sitepages/communicationsite`. For example, these are the endpoints for the commands listed above:
+- **Create**. Create a new SharePoint Communication site.
+- **Status**. Get the status of a SharePoint Communication site.
+
+The URL for Communication site REST commands is based on `_api/sitepages/communicationsite`. For example, these are the endpoints for the REST commands listed earlier:
 
 - `http:///_api/sitepages/communicationsite/create`
 - `http:///_api/sitepages/communicationsite/status`
 
-## Create Communication Site
+## Create Communication site
 
 ```
 url: /_api/sitepages/communicationsite/create
@@ -39,17 +47,17 @@ body:
 ```
 
 > [!IMPORTANT]
-> lcid parameter is not currently supported with this API. You can currently only create English sites. 
+> The `lcid` parameter is not currently supported with this API. You can currently only create English sites. 
 
-New in this API is the concept of SiteDesignID. Much like the in-product site creation flow, the SiteDesignID parameter maps to the included site designs. They are:
+New in this API is the concept of `SiteDesignID`. Much like the in-product site creation flow, the `SiteDesignID` parameter maps to the included site designs. They are:
 
 - Topic: null
 - Showcase: 6142d2a0-63a5-4ba0-aede-d9fefca2c767
 - Blank: f6cc5403-0d63-442e-96c0-285923709ffc
 
-**Response**
+### Response
 
-If successful, this method returns 200, OK response code and simple JSON object in the response body with following details.
+If successful, this method returns a `200, OK` response code and simple JSON object in the response body with the following details.
 
 ```
 {
@@ -64,21 +72,21 @@ If successful, this method returns 200, OK response code and simple JSON object
 ```
 
 
-## Get Communication Site Status
+## Get Communication site status
 
-REST API for getting the status of a modern SharePoint Communication site
+The REST API for getting the status of a modern SharePoint Communication site:
 
 ```
 url: /_api/sitepages/communicationsite/status?url='https%3A%2F%2Fcontoso.sharepoint.com%2Fsites%2Fcomm1'
 method: GET
 body: none
 ```
 
-**Response**
+### Response
 
-If successful, this method returns 200, OK response code and simple JSON object in the response body with following details.
+If successful, this method returns a `200, OK` response code and simple JSON object in the response body with the following details.
 
-If the site exists, the response will return the site status and site URL.
+If the site exists, the response returns the site status and site URL:
 
 ```
 {
@@ -92,7 +100,7 @@ If the site exists, the response will return the site status and site URL.
 }
 ```
 
-If the site does not exist, the response will return site status of 0 with no URL.
+If the site does not exist, the response returns a site status of 0 with no URL.
 
 ```
 {
@@ -104,4 +112,8 @@ If the site does not exist, the response will return site status of 0 with no UR
       }
   }
 }
-```
+```
+
+## See also
+
+- [Get to know the SharePoint REST service](../sp-add-ins/get-to-know-the-sharepoint-rest-service.md)