diff --git a/docs/api/about-apis/getting-started.md b/docs/api/about-apis/getting-started.md index c06ee558b8..bdca105cd2 100644 --- a/docs/api/about-apis/getting-started.md +++ b/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/ | diff --git a/docs/api/about-apis/intro-to-apis.md b/docs/api/about-apis/intro-to-apis.md index 2d9a247c4f..b14b805df2 100644 --- a/docs/api/about-apis/intro-to-apis.md +++ b/docs/api/about-apis/intro-to-apis.md @@ -9,14 +9,15 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; Thumbnail icon -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. - -Postman UI +1. You see the JSON output (or error messages if there is a problem) in the bottom panel.
Postman UI 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.
Button to download Sumo Logic OpenAPI Specification +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.
Imported API specification +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 Collector ID -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//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//sources` Collector sources @@ -353,4 +366,4 @@ Or add a new comment to an existing insight by creating comment text in the requ Insight comment -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. \ No newline at end of file +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. diff --git a/docs/reuse/api-intro.md b/docs/reuse/api-intro.md index 1381edb1a5..ce93526c55 100644 --- a/docs/reuse/api-intro.md +++ b/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) diff --git a/docs/reuse/cse-api-table.md b/docs/reuse/cse-api-table.md index c4d7e5fcb0..1612e46711 100644 --- a/docs/reuse/cse-api-table.md +++ b/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/ | diff --git a/docs/reuse/csoar-api-table.md b/docs/reuse/csoar-api-table.md index bd89bf77e6..fc40187fff 100644 --- a/docs/reuse/csoar-api-table.md +++ b/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/ | diff --git a/static/img/api/add-access-key-dialog.png b/static/img/api/add-access-key-dialog.png index 4620fb5264..9f92f7218e 100644 Binary files a/static/img/api/add-access-key-dialog.png and b/static/img/api/add-access-key-dialog.png differ diff --git a/static/img/api/collector-sources.png b/static/img/api/collector-sources.png index e1e4b8b96b..379ab9f219 100644 Binary files a/static/img/api/collector-sources.png and b/static/img/api/collector-sources.png differ diff --git a/static/img/api/imported-api.png b/static/img/api/imported-api.png new file mode 100644 index 0000000000..cda216e697 Binary files /dev/null and b/static/img/api/imported-api.png differ diff --git a/static/img/api/openapi-spec-download-button.png b/static/img/api/openapi-spec-download-button.png new file mode 100644 index 0000000000..8086637716 Binary files /dev/null and b/static/img/api/openapi-spec-download-button.png differ diff --git a/static/img/api/postman-ui.png b/static/img/api/postman-ui.png index 3c693af3bf..79e7c6191b 100644 Binary files a/static/img/api/postman-ui.png and b/static/img/api/postman-ui.png differ diff --git a/static/img/api/user-record.png b/static/img/api/user-record.png index 9f271a954a..8209a749bd 100644 Binary files a/static/img/api/user-record.png and b/static/img/api/user-record.png differ