writing rest api tutorial

Larry Franks · Larry Franks · commit 78dcf9c35f02 · 2018-08-21T09:50:03.000-04:00
diff --git a/articles/cognitive-services/Custom-Vision-Service/rest-api-tutorial.md b/articles/cognitive-services/Custom-Vision-Service/rest-api-tutorial.md
@@ -1,5 +1,5 @@
 ---
-title: Create a Custom Vision Service REST API tutorial - Azure Cognitive Services | Microsoft Docs
+title: Use the a Custom Vision Service REST API - Azure Cognitive Services | Microsoft Docs
 description: Use the REST API to create, train, test, and export a custom vision model.
 services: cognitive-services
 author: blackmist
@@ -13,24 +13,25 @@ ms.author: larryfr
 ---
 # Tutorial: Use the Custom Vision REST API
 
-Learn how to use the Custom Vision REST API to create, train, score, and export a model.
+Learn how to use the Custom Vision REST API to create, train, test, and export a model.
 
-The information in this document demonstrates how to use a REST client to work with the REST API for training the Custom Vision service. The examples show how to use the API using the [curl]() utility from a bash environment, or Windows PowerShell.
+The information in this document demonstrates how to use a REST client to work with the REST API for training the Custom Vision service. The examples show how to use the API using the `curl` utility from a bash environment and `Invoke-WebRequest` from Windows PowerShell.
 
 > [!div class="checklist"]
 > * Get keys
 > * Create a project
 > * Create tags
 > * Add images
-> * Use your own model
+> * Train and test the model
+> * Export the model
 
 ## Prerequisites
 
 * A basic familiarity with Representational State Transfer (REST). This document does not go into details on things like HTTP verbs, JSON, or other things commonly used with REST.
 
-* Either a bash (Bourne Again Shell) with the [curl]() utility or Windows PowerShell 3.0 (or greater).
+* Either a bash (Bourne Again Shell) with the [curl](https://curl.haxx.se) utility or Windows PowerShell 3.0 (or greater).
 
-* An Custom Vision account. For more information, see the [Build a classifier](getting-started-build-a-classifier.md) document.
+* A Custom Vision account. For more information, see the [Build a classifier](getting-started-build-a-classifier.md) document.
 
 ## Get keys
 
@@ -97,7 +98,7 @@ For more information on this request, see [CreateProject](https://southcentralus
 
 ### Specific domains
 
-To create a project for a specific domain, you can provide the __domain Id__ as an optional paramter. The following examples show how to retrieve a list of available domains:
+To create a project for a specific domain, you can provide the __domain ID__ as an optional parameter. The following examples show how to retrieve a list of available domains:
 
 ```bash
 curl -X GET "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/domains" -H "Training-Key: $TRAININGKEY" --data-ascii ""
@@ -158,9 +159,7 @@ $resp.Content
 
 ## Create tags
 
-When tagging images, you use a tag Id. To get a tag Id, you must create a tag or get the information for an existing tag.
-
-The following example demonstrates how to create a new tag named `cat`. Replace `{projectId}` with the ID of your project. Use the `name=` parameter to specify the name of the tag:
+To tag images, you must use a tag ID. The following example demonstrates how to create a new tag named `cat` and get a tag ID. Replace `{projectId}` with the ID of your project. Use the `name=` parameter to specify the name of the tag:
 
 ```bash
 curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/tags?name=cat" -H "Training-Key: $TRAININGKEY" --data-ascii ""
@@ -174,15 +173,15 @@ $resp = Invoke-WebRequest -Method 'POST' `
 $resp.Content
 ```
 
-The response to the request is similar to the following: 
+The response to the request is similar to the JSON document: 
 
 ```json
 {"id":"ed6f7ab6-5132-47ad-8649-3ec42ee62d43","name":"cat","description":null,"imageCount":0}
 ```
 
 Save the `id` value, as it is used when tagging images.
 
-For more information on this requst, see [CreateTag](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a829d).
+For more information on this request, see [CreateTag](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a829d).
 
 ## Add images
 
@@ -201,7 +200,7 @@ $resp = Invoke-WebRequest -Method 'POST' `
 $resp.Content
 ```
 
-The response to the request is similar to the following:
+The response to the request is similar to the following JSON document:
 
 ```json
 {
@@ -244,3 +243,139 @@ The response to the request is similar to the following:
 
 For more information on this request, see [CreateImagesFromUrls](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a8287).
 
+## Train the model
+
+The following examples demonstrate how to train the model. Replace `{projectId}` with the ID of your project:
+
+```bash
+curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/train" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii ""
+```
+
+```powershell
+$resp = Invoke-WebRequest -Method 'POST' `
+    -Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/train" `
+    -UseBasicParsing `
+    -Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" } 
+$resp.Content
+```
+
+The response to the request is similar to the following JSON document:
+
+```json
+{
+    "id": "23de09d6-42a1-413e-839e-8db6ee6d3496",
+    "name": "Iteration 1",
+    "isDefault": false,
+    "status": "Training",
+    "created": "2018-08-10T17:39:02.5766667",
+    "lastModified": "2018-08-16T17:15:07.5250661",
+    "projectId": "45d1b19b-69b8-4b22-8e7e-d1ca37504686",
+    "exportable": false,
+    "domainId": null
+}
+```
+
+Save the `id` value, as it is used to test and export the model.
+
+For more information, see [TrainProject](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a8294).
+
+## Test the model
+
+The following examples demonstrate how to perform a test of the model. Replace `{projectId}` with the ID of your project. Replace `{iterationId}` with the ID returned from training the model. Replace `https://linktotestimage` with the path to the test image.
+
+```bash
+curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/quicktest/url?iterationId={iterationId}" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii '{"url":"https://linktotestimage"}'
+```
+
+```powershell
+$resp = Invoke-WebRequest -Method 'POST' `
+    -Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/quicktest/url?iterationId={iterationId}" `
+    -UseBasicParsing `
+    -Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" } `
+    -Body '{"url":"https://linktotestimage"}'
+$resp.Content
+```
+
+The response to the request is similar to the following JSON document:
+
+```json
+{
+    "id": "369b010b-2a92-4f48-a918-4c1a0af91888",
+    "project": "45d1b19b-69b8-4b22-8e7e-d1ca37504686",
+    "iteration": "23de09d6-42a1-413e-839e-8db6ee6d3496",
+    "created": "2018-08-16T17:39:20.7944508Z",
+    "predictions": [
+        {
+            "probability": 0.8390652,
+            "tagId": "ed6f7ab6-5132-47ad-8649-3ec42ee62d43",
+            "tagName": "cat"
+        }
+    ]
+}
+```
+
+For more information, see [QuickTestImageUrl](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a828d).
+
+## Export the model
+
+Exporting a model is a two-step process. First you must specify the model format, and then request the URL for the exported model.
+
+### Request a model export
+
+The following examples demonstrate how to export a `coreml` model. Replace `{projectId}` with the ID of your project. Replace `{iterationId}` with the ID returned from training the model.
+
+```bash
+curl -X POST "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export?platform=coreml" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii ''
+```
+
+```powershell
+$resp = Invoke-WebRequest -Method 'POST' `
+    -Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export?platform=coreml" `
+    -UseBasicParsing `
+    -Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" }
+$resp.Content
+```
+
+The response to the request is similar to the following JSON document:
+
+```json
+{
+    "platform": "CoreML",
+    "status": "Exporting",
+    "downloadUri": null,
+    "flavor": null
+}
+```
+
+For more information, see [ExportIteration](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a829b).
+
+### Download the exported model
+
+The following examples demonstrate how to retrieve the URL of the exported model. Replace `{projectId}` with the ID of your project. Replace `{iterationId}` with the ID returned from training the model.
+
+```bash
+curl -X GET "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export" -H "Training-Key: $TRAININGKEY" -H "Content-Type: application/json" --data-ascii ''
+```
+
+```powershell
+$resp = Invoke-WebRequest -Method 'GET' `
+    -Uri "https://southcentralus.api.cognitive.microsoft.com/customvision/v2.0/Training/projects/{projectId}/iterations/{iterationId}/export" `
+    -UseBasicParsing `
+    -Headers @{ "Training-Key"="$trainingKey"; "Content-Type"="application/json" }
+$resp.Content
+```
+
+The response to the request is similar to the following JSON document:
+
+```json
+[
+    {
+        "platform": "CoreML",
+        "status": "Done",
+        "downloadUri": "https://linktoexportedmodel",
+        "flavor": null
+    }
+]
+```
+
+For more information, see [GetExports](https://southcentralus.dev.cognitive.microsoft.com/docs/services/d0e77c63c39c4259a298830c15188310/operations/5a59953940d86a0f3c7a829a).
