fix: edit messages

messages/graphql.md

@@ -1,44 +1,31 @@
 # summary
 
-Execute GraphQL statements
+Execute a GraphQL statement.
 
 # description
 
-Run any valid GraphQL statement via the /graphql [API](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-about.html)
+Specify the GraphQL statement with the "--body" flag, either directly at the command line or with a file that contains the statement. You can query Salesforce records using a "query" statement or use mutations to modify Salesforce records.
+
+This command uses the GraphQL API to query or modify Salesforce objects. For details about the API, and examples of queries and mutations, see https://developer.salesforce.com/docs/platform/graphql/guide/graphql-about.html.
 
 # examples
 
-- Runs the graphql query directly via the command line
+- Execute a GraphQL query on the Account object by specifying the query directly to the "--body" flag; the command uses your default org:
 
   <%= config.bin %> <%= command.id %> --body "query accounts { uiapi { query { Account { edges { node { Id \n Name { value } } } } } } }"
 
-- Runs a mutation to create an Account, with an `example.txt` file, containing
+- Read the GraphQL statement from a file called "example.txt" and execute it on an org with alias "my-org":
 
-  mutation AccountExample{
-    uiapi {
-      AccountCreate(input: {
-        Account: {
-          Name: "Trailblazer Express"
-        }
-      }) {
-        Record {
-          Id
-          Name {
-            value
-          }
-        }
-      }
-    }
-  }
+  <%= config.bin %> <%= command.id %> --body example.txt --target-org my-org
 
-<%= config.bin %> <%= command.id %> --body example.txt
+- Pipe the GraphQL statement that you want to execute from standard input to the command:
 
-will create a new account returning specified fields (Id, Name)
+  $ echo graphql | sf api request graphql --body -
 
-# flags.header.summary
+- Write the output of the command to a file called "output.txt" and include the HTTP response status and headers:
 
-HTTP header in "key:value" format.
+  <%= config.bin %> <%= command.id %> --body example.txt --stream-to-file output.txt --include
 
 # flags.body.summary
 
-File or content with GraphQL statement. Specify "-" to read from standard input.
+File or content with the GraphQL statement. Specify "-" to read from standard input.

messages/rest.md

@@ -1,35 +1,36 @@
 # summary
 
-Make an authenticated HTTP request to Salesforce REST API and print the response.
+Make an authenticated HTTP request using the Salesforce REST API.
+
+# description
+
+When sending the HTTP request with the "--body" flag, you can specify the request directly at the command line or with a file that contains the request.
+
+For a full list of supported REST endpoints and resources, see https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_list.htm.
 
 # examples
 
 - List information about limits in the org with alias "my-org":
 
   <%= config.bin %> <%= command.id %> 'limits' --target-org my-org
 
-- List all endpoints
+- List all endpoints in your default org; write the output to a file called "output.txt" and include the HTTP response status and headers:
 
-  <%= config.bin %> <%= command.id %> '/'
+  <%= config.bin %> <%= command.id %> '/' --stream-to-file output.txt --include
 
 - Get the response in XML format by specifying the "Accept" HTTP header:
 
-  <%= config.bin %> <%= command.id %> 'limits' --target-org my-org --header 'Accept: application/xml'
+  <%= config.bin %> <%= command.id %> 'limits' --header 'Accept: application/xml'
 
-- POST to create an Account object
+- Create an account record using the POST method; specify the request details directly in the "--body" flag:
 
   <%= config.bin %> <%= command.id %> 'sobjects/account' --body "{\"Name\" : \"Account from REST API\",\"ShippingCity\" : \"Boise\"}" --method POST
 
-- or with a file 'info.json' containing
-
-  {
-    "Name": "Demo",
-    "ShippingCity": "Boise"
-  }
+- Create an account record using the information in a file called "info.json":
 
-<%= config.bin %> <%= command.id %> 'sobjects/account' --body info.json --method POST
+  <%= config.bin %> <%= command.id %> 'sobjects/account' --body info.json --method POST
 
-- Update object
+- Update an account record using the PATCH method:
 
   <%= config.bin %> <%= command.id %> 'sobjects/account/<Account ID>' --body "{\"BillingCity\": \"San Francisco\"}" --method PATCH
 
@@ -43,4 +44,4 @@ HTTP header in "key:value" format.
 
 # flags.body.summary
 
-File to use as the body for the request. Specify "-" to read from standard input; specify "" for an empty body.
+File or content for the body of the HTTP request. Specify "-" to read from standard input or "" for an empty body.

package.json

@@ -58,7 +58,12 @@
     ],
     "topics": {
       "api": {
-        "description": "commands to send and interact with API calls"
+        "description": "Commands to interact with API calls.",
+        "subtopics": {
+          "request": {
+            "description": "Commands that make API requests."
+          }
+        }
       }
     },
     "flexibleTaxonomy": true

src/commands/api/request/rest.ts

@@ -17,6 +17,7 @@ const messages = Messages.loadMessages('@salesforce/plugin-api', 'rest');
 
 export class Rest extends SfCommand<void> {
   public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
   public static readonly examples = messages.getMessages('examples');
   public static state = 'beta';
   public static enableJsonFlag = false;