DOCS-1016 - Download the API specification (#5696)

* Add new section

* Update docs/api/about-apis/intro-to-apis.md

Co-authored-by: Kim (Sumo Logic) <[email protected]>

* DOCS-1016 - Suggested edits (#5697)

* Suggested edits - Intro to APIs

* Update docs/api/about-apis/intro-to-apis.md

* Update docs/api/about-apis/intro-to-apis.md

* Update docs/api/about-apis/intro-to-apis.md

* Update docs/api/about-apis/intro-to-apis.md

* Update docs/api/about-apis/intro-to-apis.md

* Update docs/api/about-apis/intro-to-apis.md

* Update docs/api/about-apis/intro-to-apis.md

---------

Co-authored-by: Kim (Sumo Logic) <[email protected]>

Author: jpipkin1

docs/api/about-apis/getting-started.md

@@ -15,9 +15,9 @@ Sumo Logic APIs follow Representational State Transfer (REST) patterns and are o
 
 ## Documentation
 
-To view our main docs, click the link below corresponding to your deployment. If you're not sure, see [How to determine your endpoint](#which-endpoint-should-i-should-use).
+To access our API documentation, navigate to the appropriate link based on your Sumo Logic deployment. If you're not sure, see [Which endpoint should I use?](#which-endpoint-should-i-should-use)
 
-| Deployment | API Docs URL                       |
+| Deployment | API documentation URL                       |
 |:-----------|:----------------------------------|
 | AU         | https://api.au.sumologic.com/docs/  |
 | CA         | https://api.ca.sumologic.com/docs/  |

docs/api/about-apis/intro-to-apis.md

@@ -9,14 +9,15 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 <img src={useBaseUrl('img/icons/operations/advanced-certificates.png')} alt="Thumbnail icon" width="50"/>
 
-Sumo Logic has a host of useful APIs across all products that can add valuable functionality to any organization by providing access to data and activities without going through the website. API calls can be used for data gathering, automation of processes, and custom reports.
+Sumo Logic has a host of useful APIs across all products that let you access data and perform actions without using the Sumo Logic UI. API calls can be used for to gather data, automate processes, and create custom reports.
 
-This article presumes that you have a solid understanding of Sumo Logic functionality: collectors, queries, security offerings, etc. While APIs are typically for "power users" looking for additional customization and access to web service resources, you also don't need a computer science degree to understand and make use of API calls. This article helps walk you through the basics and get you going with important data queries through the API.
+This article is for users who are familiar with Sumo Logic features (collectors, queries, and security tools, for example), but new to working with APIs. You don’t need a development background to follow along. We’ll cover the basics so you can start making API calls to run queries and perform tasks.
 
-In this article, you'll learn about:
-* How to create a Sumo Logic access ID/key.
-* How to access Sumo Logic APIs.
-* How to use APIs with Sumo Logic's Cloud SIEM.
+In this article, you'll learn how to:
+
+* Create a Sumo Logic access ID/key.
+* Access Sumo Logic APIs.
+* Use APIs with Sumo Logic's Cloud SIEM.
 
 ## Create an access key
 
@@ -66,11 +67,9 @@ However, most API users do not use a traditional web browser for API calls, othe
 An open source application such as [Postman](https://www.postman.com/) can be a convenient tool for testing and developing with API calls. To use Postman, download and install the app. Then:
 1. Enter the URL for the API call.
 1. Click the **Authorization** tab.
-1. Fill in the username and password fields with your Sumo Logic access ID and access key respectively. 
+1. Fill in the username and password fields with your Sumo Logic access ID and access key, respectively.
 1. Click **Send** when finished.
-1. You see the JSON output (or error messages if there is a problem) in the bottom panel.
-
-<img src={useBaseUrl('img/api/postman-ui.png')} alt="Postman UI" style={{border: '1px solid gray'}} width="800" />  
+1. You see the JSON output (or error messages if there is a problem) in the bottom panel.<br/><img src={useBaseUrl('img/api/postman-ui.png')} alt="Postman UI" style={{border: '1px solid gray'}} width="800" />  
 
 Most programming and scripting languages provide modules and libraries for making web service and API calls in code. For instance, the following Python code can make the same "get collectors" call programmatically using the `requests` library:
 
@@ -98,6 +97,18 @@ if __name__ == '__main__':
 
 As you are learning how APIs work, we recommend setting up an API test program, then follow along with the API examples shown in the following sections. To execute API commands, you can use Postman as shown above, another API test application, or set up a quick code snippet in Python or the programming language of your choice.
 
+### Download the OpenAPI Specification
+
+Optionally, you can download the OpenAPI Specification for the Sumo Logic API and import it to your API test application. This lets you view the full specification for all Sumo Logic APIs and run them directly from your testing tool.
+
+1. Select the API documentation URL for your deployment from the [Documentation](/docs/api/about-apis/getting-started/#documentation) section of the *API Authentication, Endpoints, and Security* article. For instance, US users would access either https://api.sumologic.com/docs/ or https://api.us2.sumologic.com/docs/. 
+1. Click the **Download** button at the top of the page. <br/><img src={useBaseUrl('img/api/openapi-spec-download-button.png')} alt="Button to download Sumo Logic OpenAPI Specification" style={{border: '1px solid gray'}} width="600" />
+1. Import the downloaded file to your API test application. For example, to [import the file to Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data/), select **File > Import**.
+1. The imported specification appears. Select any API to run it.<br/><img src={useBaseUrl('img/api/imported-api.png')} alt="Imported API specification" style={{border: '1px solid gray'}} width="500" />
+1. You can also download the API specification for Cloud SIEM or Cloud SOAR from the following locations. Simply select the API documentation URL for your deployment and click the **Download** button at the top of the page:
+     * [Cloud SIEM API documentation](/docs/api/cloud-siem-enterprise/#documentation)
+     * [Cloud SOAR API documentation](/docs/api/cloud-soar/#documentation)
+
 ## Basic API GET commands
 
 Retrieving system data and configuration is one of the most common use cases for utilizing platform APIs. These data retrieval operations are generally known as GET commands in reference to the "GET" verb used by the HTTP protocol. Data retrieved through API calls can be processed by outside applications and scripts for report generation and advanced analytics, extending functionality beyond that offered by the Sumo Logic website.
@@ -116,7 +127,9 @@ Note the first ID from your list or the sample ID shown above from the Sumo Logi
 
 <img src={useBaseUrl('img/api/collector-id.png')} alt="Collector ID" style={{border: '1px solid gray'}} width="800" />  
 
-Note that the collector data itself also contains a helpful follow-up link to analyze the sources currently configured for our chosen collector. Follow up by clicking on (or copying into the URL field) the given URL for sources:  `https://api.sumologic.com/api/v1/collectors/<collectorID>/sources`
+Note that the collector data itself also contains a helpful follow-up link to analyze the sources currently configured for our chosen collector. Follow up by clicking on (or copying into the URL field) the given URL for sources:
+
+`https://api.sumologic.com/api/v1/collectors/<collectorID>/sources`
 
 <img src={useBaseUrl('img/api/collector-sources.png')} alt="Collector sources" style={{border: '1px solid gray'}} width="800" />  
 
@@ -353,4 +366,4 @@ Or add a new comment to an existing insight by creating comment text in the requ
 
 <img src={useBaseUrl('img/api/insight-comment.png')} alt="Insight comment" style={{border: '1px solid gray'}} width="800" />
 
-All elements of Cloud SIEM functionality are available through the API, including rules, match lists, automations, tags, and custom actions. Users can even use the API to generate their own insights based on a custom selection of signals.
+All elements of Cloud SIEM functionality are available through the API, including rules, match lists, automations, tags, and custom actions. Users can even use the API to generate their own insights based on a custom selection of signals.

docs/reuse/api-intro.md

@@ -2,4 +2,4 @@ To get started with Sumo Logic APIs, see [API Authentication, Endpoints, and Sec
 
 Our APIs are built with [OpenAPI](https://www.openapis.org/). You can generate client libraries in several languages and explore automated testing.
 
-To access our API documentation, navigate to the appropriate link based on your Sumo deployment. Deployment types differ based on geographic location and account creation date. If unsure, see [Which endpoint should I use?](/docs/api/about-apis/getting-started#which-endpoint-should-i-should-use)
+To access our API documentation, navigate to the appropriate link based on your Sumo Logic deployment. Deployment types differ based on geographic location and account creation date. If unsure, see [Which endpoint should I use?](/docs/api/about-apis/getting-started#which-endpoint-should-i-should-use)

docs/reuse/cse-api-table.md

@@ -1,4 +1,4 @@
-| Deployment | Documentation URL                                         |
+| Deployment | API documentation URL                                         |
 |:-----------|:----------------------------------------------------------|
 | AU         | https://api.au.sumologic.com/docs/sec/  |
 | CA         | https://api.ca.sumologic.com/docs/sec/  |

docs/reuse/csoar-api-table.md

@@ -1,4 +1,4 @@
-| Deployment | Documentation URL                                         |
+| Deployment | API documentation URL                                         |
 |:-----------|:----------------------------------------------------------|
 | AU         | https://api.au.sumologic.com/docs/csoar/  |
 | CA         | https://api.ca.sumologic.com/docs/csoar/  |