feature: Add an overview for the Codacy API DOCS-224 (#556)

* wip: Create new section dedicated to the Codacy API

* wip: Move "Codacy API tokens" inside the new "Codacy API" section

I didn't create redirects from the previous URL to the new one because
the previous URL was live for only a very short while (see
#554).

* wip: Move example "Adding repositories" inside "Codacy API"

* clean: Rename "Codacy API overview" to "Using the Codacy API"

The new title is more "actionable" and hopefully will attract the
attention from the users better.

* feature: Add API reference links to sidebar navigation

* feature: Add Codacy API overview for both API versions

* edit: Open links API links on new browser window

* style: Refactor API overview using a table to organize the information

* clean: Improve warning about keeping API tokens safe

* feature: Add instructions on how to authenticate in the Codacy API

* clean: Move Codacy API to top level section

* feature: Add card for the Codacy API on the documentation homepage

* edit: Mention that the API v3 is preferred over the older version

* feature: Mention that Codacy Sef-hosted requires a different base URL

docs/assets/includes/api-token-warning.txt

@@ -1,4 +1,4 @@
 !!! warning
-    **Never write API tokens on your configuration files** and keep your API tokens well protected, as they grant owner permissions to your projects.
+    **Never write API tokens on your configuration files** and keep your API tokens well protected, as they grant owner permissions to your projects on Codacy.
 
     We recommend that you set API tokens as environment variables. Check the documentation of your CI/CD platform on how to do this.

docs/faq/repositories/how-do-i-programmatically-add-repositories-to-codacy.md → docs/codacy-api/adding-repositories-to-codacy-programmatically.md

@@ -1,4 +1,4 @@
-# How do I programmatically add repositories to Codacy?
+# Adding repositories to Codacy programmatically
 
 There are scenarios where manually adding Git repositories on the Codacy UI is inconvenient or time-consuming. For example:
 
@@ -16,7 +16,7 @@ curl -X POST https://app.codacy.com/api/v3/repositories \
 
 Substitute the placeholders with your own values:
 
--   **API_KEY:** [Account API token](../../related-tools/codacy-api-tokens.md#account-api-tokens) used to authenticate on the Codacy API.
+-   **API_KEY:** [Account API token](api-tokens.md#account-api-tokens) used to authenticate on the Codacy API.
 -   **GIT_PROVIDER:** Git provider hosting the repository, using one of the values in the table below. For example, `gh` for GitHub Cloud.
 
     | Value | Git provider         |
@@ -33,7 +33,7 @@ Substitute the placeholders with your own values:
     !!! important
         **If you are using GitLab** you must specify the full group path and the repository using the format `<group>/<subgroup-1>/.../<subgroup-N>/<repository>`.
 
-Currently, Codacy doesn't provide API endpoints to automate other parts of setting up new repositories, such as configuring the repository settings or the enabled code patterns. However, Codacy automatically applies the [default patterns](../../repositories-configure/code-patterns.md#set-default) defined on the Codacy API token account to the new repositories, and you can use this to ensure that all new repositories share the same pattern configuration.
+Currently, Codacy doesn't provide API endpoints to automate other parts of setting up new repositories, such as configuring the repository settings or the enabled code patterns. However, Codacy automatically applies the [default patterns](../repositories-configure/code-patterns.md#set-default) defined on the Codacy API token account to the new repositories, and you can use this to ensure that all new repositories share the same pattern configuration.
 
 ## Example: Adding all repositories in a GitHub organization
 
@@ -52,7 +52,7 @@ We provide an example Bash script that adds all repositories in a GitHub Cloud o
 
 The example script:
 
-1.  Defines a GitHub [personal access token](https://github.com/settings/tokens){: target="_blank"}, the GitHub organization name, and an [account API token](../../related-tools/codacy-api-tokens.md#account-api-tokens).
+1.  Defines a GitHub [personal access token](https://github.com/settings/tokens){: target="_blank"}, the GitHub organization name, and an [account API token](api-tokens.md#account-api-tokens).
 1.  Calls the GitHub API to [obtain the list of all repositories](https://docs.github.com/en/rest/reference/repos#list-organization-repositories){: target="_blank"} in the defined organization.
 1.  Uses [jq](https://github.com/stedolan/jq){: target="_blank"} to return the value of `full_name` for each repository obtained in the JSON response. The `full_name` already includes the organization and repository names using the format `<organization>/<repository>`.
 1.  For each repository, calls the Codacy API endpoint to add a new repository specifying `gh` as the Git provider and the value of `full_name` as the full path of the repository.

docs/related-tools/codacy-api-tokens.md → docs/codacy-api/api-tokens.md

@@ -1,8 +1,10 @@
-# Codacy API tokens
+# API tokens
 
-API tokens allow you to authenticate when using the Codacy API by including them in the headers of your API calls. See how to authenticate using the Codacy [API v2](https://api.codacy.com/swagger#authentication) and [API v3](https://api.codacy.com/api/api-docs#authentication).
+The Codacy API tokens allow you to:
 
-You also need an API token when [uploading coverage data to Codacy](../coverage-reporter/index.md) or [uploading the results of running local analysis](local-analysis/running-local-analysis.md).
+-   [Authenticate when using the Codacy API](using-the-codacy-api.md#authenticating-requests-to-the-codacy-api)
+
+-   [Upload coverage data](../coverage-reporter/index.md) or [upload the results of running local analysis](../related-tools/local-analysis/running-local-analysis.md) to Codacy
 
 Codacy provides two types of API tokens:
 
@@ -49,6 +51,6 @@ To revoke a project API token, click the trash can icon for the corresponding **
 ## See also
 
 -   [Adding coverage to your repository](../coverage-reporter/index.md)
--   [Running local analysis](local-analysis/running-local-analysis.md)
--   [Client-side tools](local-analysis/client-side-tools.md)
+-   [Running local analysis](../related-tools/local-analysis/running-local-analysis.md)
+-   [Client-side tools](../related-tools/local-analysis/client-side-tools.md)
 

docs/codacy-api/using-the-codacy-api.md

@@ -0,0 +1,73 @@
+# Using the Codacy API
+
+The Codacy API allows you to programmatically retrieve and analyze data from Codacy and perform a few configuration changes.
+
+Codacy supports two API versions but prefer the new API v3 when possible since it's the version being actively developed:
+
+<table>
+  <thead>
+    <tr>
+      <td></td>
+      <th><strong>API v3 (preferred)</strong></th>
+      <th><strong>API v2</strong></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>Endpoint documentation</th>
+      <td><a target="_blank" href="https://api.codacy.com/api/api-docs">https://api.codacy.com/api/api-docs</a></td>
+      <td><a target="_blank" href="https://api.codacy.com/swagger">https://api.codacy.com/swagger</a></td>
+    </tr>
+    <tr>
+      <th>Base URL</th>
+      <td><code>https://api.codacy.com/api/v3</code></td>
+      <td><code>https://api.codacy.com/</code></td>
+    </tr>
+    <tr>
+      <th>Overview</th>
+      <td>
+        <p>The new endpoints allow you to access and manipulate the following resources, among others:<p>
+        <ul>
+          <li><a target="_blank" href="https://api.codacy.com/api/api-docs#codacy-api-analysis">Analysis</a> details, issue and ignored issue details, repository quality settings</li>
+          <li><a target="_blank" href="https://api.codacy.com/api/api-docs#codacy-api-account">Account</a> details and API token management</li>
+          <li><a target="_blank" href="https://api.codacy.com/api/api-docs#codacy-api-organization">Organization</a> details and join request management</li>
+          <li><a target="_blank" href="https://api.codacy.com/api/api-docs#codacy-api-people">People</a> management</li>
+          <li><a target="_blank" href="https://api.codacy.com/api/api-docs#codacy-api-repository">Repository</a> management and file details</li>
+          <li><a target="_blank" href="https://api.codacy.com/api/api-docs#codacy-api-tools">Tool</a> and code pattern details</li>
+        </ul>
+      </td>
+      <td>
+        <p>The legacy endpoints allow you to access and manipulate the following resources:</p>
+          <ul>
+            <li><a target="_blank" href="https://api.codacy.com/swagger#codacy-api-commit">Commit</a> code quality details and deltas</li>
+            <li><a target="_blank" href="https://api.codacy.com/swagger#codacy-api-project">Project</a> details and configurations, file code quality and issue details</li>
+          </ul>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+!!! important
+    **If you're using Codacy Self-hosted** you must update the base URL of the APIs to include your Codacy instance domain name. For example:
+
+    ```
+    https://codacy.example.com/api/v3	
+    ```
+
+## Authenticating requests to the Codacy API
+
+Most API endpoints require that you provide either a [project or account API token](api-tokens.md). After obtaining the necessary tokens, include them in your request headers using the format `api-token: <token key>` or `project-token: <token key>`.
+
+For example, to make a request to an API v3 endpoint that requires an **account API token**:
+
+```bash
+curl -X GET https://api.codacy.com/api/v3/user/organizations/gh \
+     -H "api-token: SjE9y7ekgKdpaCofsAhd"
+```
+
+Or to make a request to an API v2 endpoint that requires a **project API token**:
+
+```bash
+curl -X GET https://api.codacy.com/2.0/commit/da275c14ffab6e402dcc6009828067ffa44b7ee0 \
+     -H "project-token: c9f2feb28e780acc8dc40754978b8bd9"
+```

docs/index.md

@@ -33,15 +33,6 @@
 <h2>Most popular topics</h2>
 
 <div class="topic-row">
-  <a class="topic-card" href="repositories-configure/code-patterns/">
-    <div class="tc-icon">
-      <img alt="Configuring code patterns" src="/assets/images/icon-checkmark.svg">
-    </div>
-    <div class="tc-content">
-      <div>Configuring code patterns</div>
-      <div>Adapt Codacy to your scenario by configuring the code patterns used to analyze your repositories</div>
-    </div>
-  </a>
   <a class="topic-card" href="coverage-reporter/">
     <div class="tc-icon">
       <img alt="Adding coverage reports" src="/assets/images/icon-checklist.svg">
@@ -57,7 +48,16 @@
     </div>
     <div class="tc-content">
       <div>Managing people in organizations</div>
-      <div>Invite your team members to join your organization on Codacy so that Codacy analyzes their commits on private repositories.</div>
+      <div>Invite your team members to join Codacy to analyze their commits on private repositories.</div>
+    </div>
+  </a>
+  <a class="topic-card" href="codacy-api/using-the-codacy-api/">
+    <div class="tc-icon">
+      <img alt="Using the Codacy API" src="/assets/images/icon-code.svg">
+    </div>
+    <div class="tc-content">
+      <div>Using the Codacy API</div>
+      <div>Programmatically retrieve and analyze data from Codacy and perform configuration changes</div>
     </div>
   </a>
 </div>

docs/related-tools/local-analysis/running-aligncheck.md

@@ -8,7 +8,7 @@ To run aligncheck as a [client-side tool](client-side-tools.md):
 
     ![Run analysis through build server](images/run-analysis-through-build-server.png)
 
-1.  Obtain a [project API token](../codacy-api-tokens.md#project-api-tokens) for your repository.
+1.  Obtain a [project API token](../../codacy-api/api-tokens.md#project-api-tokens) for your repository.
 
     You need the project API token to allow the Codacy Analysis CLI to authenticate to Codacy when reporting the analysis results.
 

docs/related-tools/local-analysis/running-deadcode.md

@@ -8,7 +8,7 @@ To run deadcode as a [client-side tool](client-side-tools.md):
 
     ![Run analysis through build server](images/run-analysis-through-build-server.png)
 
-1.  Obtain a [project API token](../codacy-api-tokens.md#project-api-tokens) for your repository.
+1.  Obtain a [project API token](../../codacy-api/api-tokens.md#project-api-tokens) for your repository.
 
     You need the project API token to allow the Codacy Analysis CLI to authenticate to Codacy when reporting the analysis results.
 

docs/related-tools/local-analysis/running-spotbugs.md

@@ -8,7 +8,7 @@ To run SpotBugs as a [client-side tool](client-side-tools.md):
 
     ![Run analysis through build server](images/run-analysis-through-build-server.png)
 
-1.  Obtain a [project API token](../codacy-api-tokens.md#project-api-tokens) for your repository.
+1.  Obtain a [project API token](../../codacy-api/api-tokens.md#project-api-tokens) for your repository.
 
     You need the project API token to allow the Codacy Analysis CLI to authenticate to Codacy when reporting the analysis results.
 

mkdocs.yml

@@ -74,8 +74,8 @@ plugins:
               "hc.md": "index.md"
               "hc/en-us.md": "index.md"
               "hc/en-us/requests/new.md": "https://codacy.zendesk.com/hc/en-us/requests/new"
-              "hc/en-us/articles/115000255385.md": "related-tools/codacy-api-tokens.md"
-              "hc/en-us/articles/115000255385-API-Tokens.md": "related-tools/codacy-api-tokens.md"
+              "hc/en-us/articles/115000255385.md": "codacy-api/api-tokens.md"
+              "hc/en-us/articles/115000255385-API-Tokens.md": "codacy-api/api-tokens.md"
               "hc/en-us/articles/115000282129.md": "faq/troubleshooting/why-cant-i-configure-post-commit-hooks-and-integrations.md"
               "hc/en-us/articles/115000282129-Why-can-t-I-configure-post-commit-hooks-and-integrations-.md": "faq/troubleshooting/why-cant-i-configure-post-commit-hooks-and-integrations.md"
               "hc/en-us/articles/115000488285.md": "repositories-configure/integrations/slack-integration.md"
@@ -140,8 +140,8 @@ plugins:
               "hc/en-us/articles/207994395.md": "repositories-configure/file-extensions.md"
               "hc/en-us/articles/207994395-File-Extensions.md": "repositories-configure/file-extensions.md"
               "hc/en-us/articles/207994395-Language-Extensions.md": "repositories-configure/file-extensions.md"
-              "hc/en-us/articles/207994675.md": "related-tools/codacy-api-tokens.md"
-              "hc/en-us/articles/207994675-Project-API.md": "related-tools/codacy-api-tokens.md"
+              "hc/en-us/articles/207994675.md": "codacy-api/api-tokens.md"
+              "hc/en-us/articles/207994675-Project-API.md": "codacy-api/api-tokens.md"
               "hc/en-us/articles/207994725.md": "related-tools/codacy-plugin-tools.md"
               "hc/en-us/articles/207994725-Tool-Developer-Guide.md": "related-tools/codacy-plugin-tools.md"
               "hc/en-us/articles/207994735.md": "getting-started/supported-languages-and-tools.md"
@@ -484,7 +484,7 @@ plugins:
               "repositories-configure/php_codesniffer-specifying-your-php-version.md": "repositories-configure/codacy-configuration-file.md"
               "release-notes/cloud/removal-of-nodesecurity,-golint-and-scsslint.md": "release-notes/cloud/removal-of-nodesecurity-golint-and-scsslint.md"
               "getting-started/i-added-a-repository-now-what.md": "getting-started/getting-started-with-codacy.md"
-              "related-tools/api-tokens.md": "related-tools/codacy-api-tokens.md"
+              "related-tools/api-tokens.md": "codacy-api/api-tokens.md"
               "faq/troubleshooting/why-isnt-my-public-repository-being-analysed.md": "faq/troubleshooting/why-isnt-my-public-repository-being-analyzed.md"
               "related-tools/running-local-analysis.md": "related-tools/local-analysis/running-local-analysis.md"
               "related-tools/run-local-analysis.md": "related-tools/local-analysis/running-local-analysis.md"
@@ -505,8 +505,9 @@ plugins:
               "coverage-reporter/generating-coverage-reports.md": "coverage-reporter/index.md"
               "coverage-reporter/adding-coverage-to-your-repository.md": "coverage-reporter/index.md"
               "faq/code-analysis/error-line-endings.md": "faq/troubleshooting/error-line-endings.md"
-              "repositories-configure/integrations/project-api.md": "related-tools/codacy-api-tokens.md"
               "repositories-configure/code-standards.md": "faq/code-analysis/how-to-configure-php-codesniffer-code-standards.md"
+              "repositories-configure/integrations/project-api.md": "codacy-api/api-tokens.md"
+              "faq/repositories/how-do-i-programmatically-add-repositories-to-codacy.md": "codacy-api/adding-repositories-to-codacy-programmatically.md"
 
 nav:
     - Documentation home: "index.md"
@@ -561,8 +562,13 @@ nav:
                 - related-tools/local-analysis/running-aligncheck.md
                 - related-tools/local-analysis/running-deadcode.md
                 - related-tools/local-analysis/running-spotbugs.md
-          - related-tools/codacy-api-tokens.md
           - related-tools/codacy-plugin-tools.md
+    - Codacy API:
+          - codacy-api/using-the-codacy-api.md
+          - codacy-api/api-tokens.md
+          - codacy-api/adding-repositories-to-codacy-programmatically.md
+          - API v3 reference (preferred): https://api.codacy.com/api/api-docs
+          - API v2 reference: https://api.codacy.com/swagger
     - Installing Codacy: "!include submodules/chart/mkdocs.yml"
     - Troubleshooting and FAQs:
           - General:
@@ -583,7 +589,6 @@ nav:
                 - faq/repositories/how-do-i-set-codacy-as-a-required-check-to-merge-prs.md
                 - faq/repositories/how-do-i-manually-force-a-repository-update.md
                 - faq/repositories/how-do-i-reanalyze-my-repository.md
-                - faq/repositories/how-do-i-programmatically-add-repositories-to-codacy.md
                 - faq/repositories/i-renamed-my-repository-on-the-git-provider.md
                 - faq/repositories/i-moved-my-repository-on-the-git-provider.md
                 - faq/repositories/how-do-i-migrate-a-legacy-repository-to-a-synced-organization.md