Merge pull request circleci#4442 from circleci/tjs/fix/api-developer-guides-headings

teesloane · web-flow · commit dd305ca44ef8 · 2020-06-09T11:28:27.000-04:00
Clean: only use &gt;= 2 level headings for content.
diff --git a/jekyll/_cci2/api-developers-guide.md b/jekyll/_cci2/api-developers-guide.md
@@ -59,7 +59,7 @@ To add an API token, perform the steps listed below.
 
 **Note:** All API calls are made in the same way, by making standard HTTP calls, using JSON, a content-type, and your API token. Please note that the JSON examples shown in this document are not comprehensive and may contain additional JSON response fields not shown in the example, based on user input and fields.
 
-# Getting Started with the API
+## Getting Started with the API
 
 The CircleCI API shares similarities with previous API versions in that it identifies your projects using repository name. For instance, if you want to pull information from CircleCI about the GitHub repository https://github.com/CircleCI-Public/circleci-cli you can refer to that in the CircleCI API as `gh/CircleCI-Public/circleci-cli`, which is a “triplet” of the project type (VCS provider), the name of your “organization” (or your username), and the name of the repository. 
 
@@ -75,23 +75,23 @@ The `project_slug` is included in the payload when pulling information about a p
 
 ![API structure]({{ site.baseurl }}/assets/img/docs/api-structure.png)
 
-# HTTP Status Codes and Response Handling
+## HTTP Status Codes and Response Handling
 
 When you make an API request to the server, an HTTP status code is returned along with the JSON body response. The CircleCI API v2 adheres to standard HTTP response codes, which include the following status code definitions:
 
 * 200 - Success
 * 400 - Client error
 * 500 - Server error
 
-## 200 Status Codes
+### 200 Status Codes
 
 If you receive a 200 HTTP status code, your API request is successful and the requested resource will be returned. The following 200 HTTP status codes could potentially be returned with your request:
 
 * 200 - OK
 * 201 - Created
 * 202 - Accepted
 
-## 400 Status Codes
+### 400 Status Codes
 
 If you receive a 400 HTTP status code, there is a problem with the request and the server is unable to successfully process the request. The following status codes may be returned with your request:
 
@@ -100,13 +100,13 @@ If you receive a 400 HTTP status code, there is a problem with the request and t
 * 404 - Not Found
 * 429 - Too Many Requests (see [rate limits](#rate-limits)).
 
-## 500 Status Code
+### 500 Status Code
 
 If you receive a 500 HTTP status code, there is a problem with the server and the request cannot be processed. If you encounter a 500 response, the error will be logged and CircleCI will work to resolve the error. The following 500 HTTP status codes could potentially be returned with your request:
 
 * 500 - Internal Server Error
 
-# Rate Limits
+## Rate Limits
 
 The CircleCI API is protected by a number of rate limiting measures to ensure the stability of the system. We reserve the right to throttle the requests made by an individual user, or the requests made to individual resources in order to ensure a fair level of service to all of our users.
 
@@ -116,22 +116,22 @@ There are different protections and limits in place for different parts of the A
 For HTTP APIs, when a request is throttled, you will receive [HTTP status code 429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429). If your integration requires that a throttled request is completed, then you should retry these requests after a delay, using an exponential backoff.
 In most cases, the HTTP 429 response code will be accompanied by the [Retry-After HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). When this header is present, your integration should wait for the period of time specified by the header value before retrying a request.
 
-# REST API Tutorial
+## REST API Tutorial
 
 For more detailed information about HTTP status codes, refer to the [rest api tutorial](http://www.restapitutorial.com/httpstatuscodes.html).
 
-# Example End-to-End API Request
+## Example End-to-End API Request
 
 The following section details the steps you would need, from start to finish, to make an API call. This section includes creating a "demo repository" called "hello-world", however, you can use a pre-existing repository to follow along if you choose.
 
 **NOTE:** Many of the API calls make use of the `{project-slug}` triplet, described [above](#getting-started-with-the-api). 
 
-## Prerequisites
+### Prerequisites
 
 * A GitHub or BitBucket account with a repository to setup with CircleCI.
 * Completion of the CircleCI onboarding.
 
-## Steps
+### Steps
 
 1. On your VCS provider, create a repository. The repo for this example will be called `hello-world`.
 
@@ -262,7 +262,7 @@ The following section details the steps you would need, from start to finish, to
 
 This concludes the end-to-end example of using the V2 API. For more detailed information about other endpoints you may wish to call, please refer to the [CircleCI API v2 Documentation]({{site.baseurl}}/api/v2/#circleci-api) for an overview of all endpoints currently available.
 
-# Additional API Use Cases
+## Additional API Use Cases
 
 Now that you have a general understanding of how the CircleCI API v2 service works through an end-to-end API example request and walkthrough, let's look at a few common tasks and operations you may perform on a regular basis when using the API. Whether you wish to return information about a job or project, or retrieve more detailed information about a project by reviewing its artifacts, the examples shown below should assist you in gaining a better understanding of how to make some API requests to the server so you can perform a deep dive into the specifics of your work.
 
@@ -281,7 +281,7 @@ This section provides detailed information on how you can perform the following
 * [Download artifacts](#download-artifacts)
 * [Gather Insights](#gather-insights)
 
-## Get Project Details
+### Get Project Details
 
 You may often find that it would be helpful to retrieve information about a specific project, including the name of the organization the project belongs to, the version control system (vcs) that hosts the project, and other details. The CircleCI API enables you to return this and other information by making a single GET request to the `project/{project-slug}` endpoint by passing the `project-slug` parameter.
 
@@ -295,7 +295,7 @@ The `project_slug` is included in the payload when you pull information about a
 
 **Note** If you would like more detailed information about a project, or simply need a refresher on the specifics of a project, please refer to the CircleCI [Projects](https://circleci.com/docs/2.0/projects/) page.
 
-### Steps
+#### Steps
 
 Of the several project-related API endpoints available with CircleCI API v2, making a GET request to the `/project/{project-slug}` endpoint enables you to return detailed information about a specific project by passing the `project_slug` parameter with your request.
 
@@ -329,13 +329,13 @@ To return project details, perform the following steps:
 
 Notice in the example above that you will receive very specific information about your project, including the name of the project, the name of the organization that the project belongs to, and information about the VCS that hosts the project. For a more detailed breakdown of each value returned in this request, please refer to the [Get Project Details](https://circleci.com/docs/api/v2/#get-a-project) section of the *CircleCI API v2 Reference Guide*.
 
-## Get Job Details
+### Get Job Details
 
 Much like the Get Project Details API request described in the previous example, the Get Job Details API request enables you to return specific job information from the CircleCI API by making a single API request. Retrieving job information can be very useful when you want information about how your job performed, what resources were used (e.g. pipeline, executor type, etc.), and the time it took for the job to finish.
 
 Please remember, jobs are collections of steps. Each job must declare an executor that is either `docker`, `machine`, `windows` or `macos`. `machine` includes a default image if not specified, for `docker` you must specify an image to use for the primary container, for `macos` you must specify an Xcode version, and for `windows` you must use the Windows orb.
 
-### Steps
+#### Steps
 
 Of the several Jobs-related API endpoints available with CircleCI API v2, there is a specific endpoint you may wish to call to receive detailed information about your job. This API call to the `GET /project/{project_slug}/job/{job-number}`endpoint enables you to return detailed information about a specific job by passing the `project-slug` and `job-number` parameters with your request.
 
@@ -404,11 +404,11 @@ Notice in the example above that you will receive very specific information abou
 
 For a more detailed breakdown of each value returned in this request, please refer to the [Get Job Details](https://circleci.com/docs/api/v2/#get-job-details) section of the *CircleCI API v2 Reference Guide*.
 
-## Download Artifacts
+### Download Artifacts
 
 The following section details the steps you need to follow to download artifacts that are generated when a job is run, first, returning a list of artifacts for a job, and then downloading the full set of artifacts. If you are looking for instructions for downloading the _latest_ artifacts for a pipeline, without needing to specify a job number, see our [API v1.1 guide](https://circleci.com/docs/2.0/artifacts/#downloading-all-artifacts-for-a-build-on-circleci) – keep checking back here as this functionality will be added to API v2 in the future.
 
-### Steps
+#### Steps
 
 1. First, we will ensure your API token is set as an environment variable. You maybe have already done this during authentication, but if not, run the following command in your terminal, substituting your personal API token:
 
@@ -462,11 +462,11 @@ The following section details the steps you need to follow to download artifacts
 
     **Note:** `grep` is used to locate all the URLs for downloading the job artifacts, while `wget` is used to perform the download.
 
-## Gather Insights
+### Gather Insights
 
 The CircleCI API v2 also includes several endpoints that enable you to retrieve detailed insights into your workflows and individual jobs. By making API calls to these endpoints, you can better understand how to optimize your workflows and jobs so you can increase workflow performance while minimizing credit usage and consumption. The example below describes how you can return information about a single workflow containg information about metrics and credit usage.
 
-### Returning Workflow Metrics
+#### Returning Workflow Metrics
 
 To return aggregated data for an individual workflow, perform the steps listed below.
 
@@ -566,7 +566,7 @@ Notice that in this JSON response, you will receive detailed metrics for the set
 
 **Note** The above example only shows just a few builds. When you run this command, you may receive up to 250 individual builds that you can review in much more detail.
 
-### Reviewing Individual Job Metrics
+#### Reviewing Individual Job Metrics
 
 Now that you have retrieved aggregated data for up to 250 different jobs, you will most likely want to review specific information about a single job, or smaller number of jobs, to ensure that your jobs are running efficiently. To review an individual job, follow the steps below.
 
@@ -643,23 +643,23 @@ When reviewing each individual review job, please note that the following inform
 - `stopped_at` - The time the job ended.
 - `credits_used` - The number of credits used during the job.
 
-# Reference
+## Reference
 
-## API Endpoints
+### API Endpoints
 
 The CircleCI v2 API, and its associated endpoints allow you to make HTTP calls to designated endpoints developed in the underlying CircleCI API architecture. These endpoints provide programmatic access to CircleCI services, including pipelines, workflows, and jobs. 
 
 Before working with the API and making calls, you should first have an understanding of the various API requests you can make to API v2 endpoints. The sections below describe these API requests.
 
-### User Endpoints
+#### User Endpoints
 
 | Endpoint               | Description                       
 |------------------------|-------------------------------------------------------
 | GET /user/{id}         | This endpoint enables you to return information about a specific user by making a GET request and passing the `id` parameter in the request |
 | GET /me/collaborations | This endoint enables you to return a list of organizations that the user is a member of, or is a collaborator by making a GET request and passing the `collaborations` parameter in the request. |
 {: class="table table-striped"}
 
-### Pipeline API Requests
+#### Pipeline API Requests
 
 | Endpoint                                  | Description                                                         | 
 |-------------------------------------------|---------------------------------------------------------------------|
@@ -671,7 +671,7 @@ Before working with the API and making calls, you should first have an understan
 | GET /project/{project-slug}/pipeline/mine | Returns all pipelines for the project that you have triggered.      |
 {: class="table table-striped"}
 
-### Project API Requests
+#### Project API Requests
 
 | Endpoint                                                  | Description                                                       |
 |-----------------------------------------------------------|-------------------------------------------------------------------|
@@ -687,7 +687,7 @@ Before working with the API and making calls, you should first have an understan
 | GET /project/{project-slug}/envvar/{name}                 | Returns a masked value for an environment variable for a project. |
 {: class="table table-striped"}
 
-### Job API Requests
+#### Job API Requests
 
 | Endpoint                                             | Description                      |        
 |------------------------------------------------------|----------------------------------|
@@ -697,7 +697,7 @@ Before working with the API and making calls, you should first have an understan
 | GET /project/{project-slug}/{job-number}/tests       | Returns test metadata for a job. |
 {: class="table table-striped"}
 
-### Workflow API Requests
+#### Workflow API Requests
 
 | Endpoint                   | Description                                  |
 |----------------------------|----------------------------------------------|
@@ -707,7 +707,7 @@ Before working with the API and making calls, you should first have an understan
 | POST /workflow/{id}/rerun  | Reruns a workflow.                           |
 {: class="table table-striped"}
 
-### Insights Requests
+#### Insights Requests
 
 | Endpoint                                                               | Description                                       |
 |------------------------------------------------------------------------|---------------------------------------------------|
@@ -717,7 +717,7 @@ Before working with the API and making calls, you should first have an understan
 | GET /insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name} | Get recent runs of a job within a workflow.       |
 {: class="table table-striped"}
 
-## See Also
+### See Also
 
 - Refer to [API V2 Introduction]({{site.baseurl}}/2.0/api-intro/) for high-level information about the CircleCI V2 API.
 - Refer to [API V2 Reference Guide]({{site.baseurl}}/api/v2/) for a detailed list of all endpoints that make up the CircleCI V2 API.
