@salesforce/plugin-api 1.2.1 → 1.3.0

package/messages/rest.md

@@ -1,6 +1,12 @@
 # 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
 
@@ -8,39 +14,71 @@ Make an authenticated HTTP request to Salesforce REST API and print the response
 
   <%= 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'
-
-- POST to create an Account object
+  <%= config.bin %> <%= command.id %> 'limits' --header 'Accept: application/xml'
 
-  <%= config.bin %> <%= command.id %> 'sobjects/account' --body "{\"Name\" : \"Account from REST API\",\"ShippingCity\" : \"Boise\"}" --method POST
+- Create an account record using the POST method; specify the request details directly in the "--body" flag:
 
-- or with a file 'info.json' containing
+  <%= config.bin %> <%= command.id %> sobjects/account --body "{\"Name\" : \"Account from REST API\",\"ShippingCity\" : \"Boise\"}" --method POST
 
-  {
-    "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
 
+- Store the values for the request header, body, and so on, in a file, which you then specify with the --file flag; see the description of --file for more information:
+
+  <%= config.bin %> <%= command.id %> --file myFile.json
+
 # flags.method.summary
 
 HTTP method for the request.
 
+# flags.file.summary
+
+JSON file that contains values for the request header, body, method, and URL.
+
+# flags.file.description
+
+Use this flag instead of specifying the request details with individual flags, such as --body or --method. This schema defines how to create the JSON file:
+
+{
+url: { raw: string } | string;
+method: 'GET', 'POST', 'PUT', 'PATCH', 'HEAD', 'DELETE', 'OPTIONS', 'TRACE';
+description?: string;
+header: string | Array<Record<string, string>>;
+body: { mode: 'raw' | 'formdata'; raw: string; formdata: FormData };
+}
+
+Salesforce CLI defined this schema to be mimic Postman schemas; both share similar properties. The CLI's schema also supports Postman Collections to reuse and share requests. As a result, you can build an API call using Postman, export and save it to a file, and then use the file as a value to this flag. For information about Postman, see https://learning.postman.com/.
+
+Here's a simple example of a JSON file that contains values for the request URL, method, and body:
+
+{
+"url": "sobjects/Account/<Account ID>",
+"method": "PATCH",
+"body" : {
+"mode": "raw",
+"raw": {
+"BillingCity": "Boise"
+}
+}
+}
+
+See more examples in the plugin-api test directory, including JSON files that use "formdata" to define collections: https://github.com/salesforcecli/plugin-api/tree/main/test/test-files/data-project.
+
 # flags.header.summary
 
 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/oclif.manifest.json

@@ -3,9 +3,12 @@
     "api:request:graphql": {
       "aliases": [],
       "args": {},
-      "description": "Run any valid GraphQL statement via the /graphql [API](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-about.html)",
+      "description": "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.\n\nThis 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\n\n  <%= config.bin %> <%= command.id %> --body \"query accounts { uiapi { query { Account { edges { node { Id \\n Name { value } } } } } } }\"\n\n- Runs a mutation to create an Account, with an `example.txt` file, containing\n\n  mutation AccountExample{\n    uiapi {\n      AccountCreate(input: {\n        Account: {\n          Name: \"Trailblazer Express\"\n        }\n      }) {\n        Record {\n          Id\n          Name {\n            value\n          }\n        }\n      }\n    }\n  }\n\n<%= config.bin %> <%= command.id %> --body example.txt\n\nwill create a new account returning specified fields (Id, Name)"
+        "Execute a GraphQL query on the Account object by specifying the query directly to the \"--body\" flag; the command uses your default org:\n<%= config.bin %> <%= command.id %> --body \"query accounts { uiapi { query { Account { edges { node { Id \\n Name { value } } } } } } }\"",
+        "Read the GraphQL statement from a file called \"example.txt\" and execute it on an org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> --body example.txt --target-org my-org",
+        "Pipe the GraphQL statement that you want to execute from standard input to the command:\n$ echo graphql | sf api request graphql --body -",
+        "Write the output of the command to a file called \"output.txt\" and include the HTTP response status and headers:\n<%= config.bin %> <%= command.id %> --body example.txt --stream-to-file output.txt --include"
       ],
       "flags": {
         "json": {
@@ -65,7 +68,7 @@
         "body": {
           "name": "body",
           "required": true,
-          "summary": "File or content with GraphQL statement. Specify \"-\" to read from standard input.",
+          "summary": "File or content with the GraphQL statement. Specify \"-\" to read from standard input.",
           "hasDynamicHelp": false,
           "helpValue": "file",
           "multiple": false,
@@ -80,7 +83,7 @@
       "pluginType": "core",
       "state": "beta",
       "strict": true,
-      "summary": "Execute GraphQL statements",
+      "summary": "Execute a GraphQL statement.",
       "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
@@ -103,14 +106,21 @@
     "api:request:rest": {
       "aliases": [],
       "args": {
-        "endpoint": {
+        "url": {
           "description": "Salesforce API endpoint",
-          "name": "endpoint",
-          "required": true
+          "name": "url",
+          "required": false
         }
       },
+      "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.\n\nFor 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\":\n\n  <%= config.bin %> <%= command.id %> 'limits' --target-org my-org\n\n- List all endpoints\n\n  <%= config.bin %> <%= command.id %> '/'\n\n- Get the response in XML format by specifying the \"Accept\" HTTP header:\n\n  <%= config.bin %> <%= command.id %> 'limits' --target-org my-org --header 'Accept: application/xml'\n\n- POST to create an Account object\n\n  <%= config.bin %> <%= command.id %> 'sobjects/account' --body \"{\\\"Name\\\" : \\\"Account from REST API\\\",\\\"ShippingCity\\\" : \\\"Boise\\\"}\" --method POST\n\n- or with a file 'info.json' containing\n\n  {\n    \"Name\": \"Demo\",\n    \"ShippingCity\": \"Boise\"\n  }\n\n<%= config.bin %> <%= command.id %> 'sobjects/account' --body info.json --method POST\n\n- Update object\n\n  <%= config.bin %> <%= command.id %> 'sobjects/account/<Account ID>' --body \"{\\\"BillingCity\\\": \\\"San Francisco\\\"}\" --method PATCH"
+        "List information about limits in the org with alias \"my-org\":\n<%= config.bin %> <%= command.id %> 'limits' --target-org my-org",
+        "List all endpoints in your default org; write the output to a file called \"output.txt\" and include the HTTP response status and headers:\n<%= config.bin %> <%= command.id %> '/' --stream-to-file output.txt --include",
+        "Get the response in XML format by specifying the \"Accept\" HTTP header:\n<%= config.bin %> <%= command.id %> 'limits' --header 'Accept: application/xml'",
+        "Create an account record using the POST method; specify the request details directly in the \"--body\" flag:\n<%= config.bin %> <%= command.id %> sobjects/account --body \"{\\\"Name\\\" : \\\"Account from REST API\\\",\\\"ShippingCity\\\" : \\\"Boise\\\"}\" --method POST",
+        "Create an account record using the information in a file called \"info.json\":\n<%= config.bin %> <%= command.id %> 'sobjects/account' --body info.json --method POST",
+        "Update an account record using the PATCH method:\n<%= config.bin %> <%= command.id %> 'sobjects/account/<Account ID>' --body \"{\\\"BillingCity\\\": \\\"San Francisco\\\"}\" --method PATCH",
+        "Store the values for the request header, body, and so on, in a file, which you then specify with the --file flag; see the description of --file for more information:\n<%= config.bin %> <%= command.id %> --file myFile.json"
       ],
       "flags": {
         "flags-dir": {
@@ -152,7 +162,6 @@
           "char": "X",
           "name": "method",
           "summary": "HTTP method for the request.",
-          "default": "GET",
           "hasDynamicHelp": false,
           "multiple": false,
           "options": [
@@ -176,6 +185,16 @@
           "multiple": true,
           "type": "option"
         },
+        "file": {
+          "char": "f",
+          "description": "Use this flag instead of specifying the request details with individual flags, such as --body or --method. This schema defines how to create the JSON file:\n\n{\nurl: { raw: string } | string;\nmethod: 'GET', 'POST', 'PUT', 'PATCH', 'HEAD', 'DELETE', 'OPTIONS', 'TRACE';\ndescription?: string;\nheader: string | Array<Record<string, string>>;\nbody: { mode: 'raw' | 'formdata'; raw: string; formdata: FormData };\n}\n\nSalesforce CLI defined this schema to be mimic Postman schemas; both share similar properties. The CLI's schema also supports Postman Collections to reuse and share requests. As a result, you can build an API call using Postman, export and save it to a file, and then use the file as a value to this flag. For information about Postman, see https://learning.postman.com/.\n\nHere's a simple example of a JSON file that contains values for the request URL, method, and body:\n\n{\n\"url\": \"sobjects/Account/<Account ID>\",\n\"method\": \"PATCH\",\n\"body\" : {\n\"mode\": \"raw\",\n\"raw\": {\n\"BillingCity\": \"Boise\"\n}\n}\n}\n\nSee more examples in the plugin-api test directory, including JSON files that use \"formdata\" to define collections: https://github.com/salesforcecli/plugin-api/tree/main/test/test-files/data-project.",
+          "name": "file",
+          "summary": "JSON file that contains values for the request header, body, method, and URL.",
+          "hasDynamicHelp": false,
+          "helpValue": "file",
+          "multiple": false,
+          "type": "option"
+        },
         "stream-to-file": {
           "char": "S",
           "exclusive": [
@@ -189,8 +208,9 @@
           "type": "option"
         },
         "body": {
+          "char": "b",
           "name": "body",
-          "summary": "File to use as the body for the request. Specify \"-\" to read from standard input; specify \"\" for an empty body.",
+          "summary": "File or content for the body of the HTTP request. Specify \"-\" to read from standard input or \"\" for an empty body.",
           "hasDynamicHelp": false,
           "helpValue": "file",
           "multiple": false,
@@ -205,7 +225,7 @@
       "pluginType": "core",
       "state": "beta",
       "strict": true,
-      "summary": "Make an authenticated HTTP request to Salesforce REST API and print the response.",
+      "summary": "Make an authenticated HTTP request using the Salesforce REST API.",
       "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
@@ -226,5 +246,5 @@
       ]
     }
   },
-  "version": "1.2.1"
+  "version": "1.3.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@salesforce/plugin-api",
     "description": "A plugin to call API endpoints via CLI commands",
-    "version": "1.2.1",
+    "version": "1.3.0",
     "author": "Salesforce",
     "bugs": "https://github.com/forcedotcom/cli/issues",
     "dependencies": {
@@ -11,6 +11,7 @@
         "@salesforce/sf-plugins-core": "^11.3.2",
         "@salesforce/ts-types": "^2.0.12",
         "ansis": "^3.3.2",
+        "form-data": "^4.0.0",
         "got": "^13.0.0",
         "proxy-agent": "^6.4.0"
     },
@@ -31,8 +32,6 @@
     "files": [
         "/lib",
         "/messages",
-        "/npm-shrinkwrap.json",
-        "/oclif.lock",
         "/oclif.manifest.json",
         "/schemas"
     ],
@@ -58,7 +57,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
@@ -202,7 +206,7 @@
     "exports": "./lib/index.js",
     "type": "module",
     "sfdx": {
-        "publicKeyUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-api/1.2.1.crt",
-        "signatureUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-api/1.2.1.sig"
+        "publicKeyUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-api/1.3.0.crt",
+        "signatureUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-api/1.3.0.sig"
     }
 }