Create analytics-api-examples.md

_docs/api-examples/analytics-api-examples.md

@@ -0,0 +1,265 @@
+---
+title: "Analytics API"
+description: ""
+group: api
+toc: true
+---
+
+
+
+The Analytics API uses HTTP POST requests with JSON arguments and JSON responses. ????
+
+
+## Authorization
+To make calls to the Analytics API, you need authorization through an API key passed in the header of the API request.  
+
+>**NOTE**  
+The user who generates the API token must be an account administrator.  
+Currently, you do not need to select specific scopes for the API key.
+
+##### How to get the API key
+1. From your avatar dropdown in the Codefresh toolbar, select **User Settings**.
+1. Do one of the following:
+  * If you have an existing API key you have saved, use that key.
+  * To generate a new API key, click **Generate**.
+    1. In **Key Name**, type a new name for the API key. 
+      This name is displayed in the UI with random numbers and letters.
+    1. Click **Create**.
+    1. Copy the API key to a handy location.
+
+
+
+
+## Get list of pipelines 
+
+Gets the list of 
+
+
+### Headers
+The API authorization token must be included in the header of the API request. See [Authorization](#authorization).
+
+```
+content-type: application/json
+Authorization: <TOKEN>
+```
+
+### Request body 
+
+For a description of the fields, see [Request parameters](#request-parameters).
+
+
+
+### Request example
+
+The request is formatted in curl.
+
+```
+curl -X POST https://codefresh-hosted-gitops-runtime.com/api/promotions/commit \
+    --header "content-type: application/json" \
+    --header "Authorization: 214ffb**************" \
+    --data 
+{
+    \"srcAppId\": {
+        \"runtime\": \"codefresh\",
+        \"namespace\": \"orders-qa\",
+        \"name\": \"orders-qa-us-east\"
+    },
+    \"destAppId\": {
+        \"runtime\": \"codefresh\",
+        \"namespace\": \"orders-prod\",
+        \"name\": \"orders-prod-us-east\"
+    },
+        \"message\": \"Update image tag and bump version\"
+}"
+```
+### Response example
+
+#### Success
+Here's an example of the response for a successful request.
+It includes the:
+* Commit SHA
+* Commit message
+* Name and email of the user who authored the commit
+
+```
+{"COMMIT_SHA":"ff46cab5a4c94fc2db215b2bd2102da05c5314ba","COMMIT_MESSAGE":"bumped version","COMMIT_AUTHOR":"codefresh-user <[email protected]>"}
+```
+#### Failure
+Here's an example of the response for a failed request when there were no changes to promote between the source and the destination applications.
+
+```
+{"statusCode":400,"message":"no changes found between source and destination applications","error":"Bad Request"}
+```
+
+
+## POST    `/promotions/pullRequest`
+
+Promotes the application from the source environment to the destination or target environment through a `pull request`  as the promotion action.
+
+### `pullRequest` request body
+
+```
+{
+        "srcAppId": {
+            "runtime": "<runtime name>",
+            "namespace": "<namespace>",
+            "name": "<source-application-name>"
+        },
+        "destAppId": {
+            "runtime": "<runtime-name>",
+            "namespace": "<namespace>",
+            "name": "<destination-application-name>"
+        },
+        "head": "<branch-of-destination-application>",
+        "title": "<pr-title>",
+        "description": "<pr-description",
+        "commitMessage": "<commit-message-when-empty-uses-title>",
+        "commitDescription": "<commit-description>",
+    }"
+```
+
+### `pullRequest` request example
+The request is formatted in curl.
+
+```
+curl -X POST https://codefresh-hosted-gitops-runtime.com/api/promotions/pullRequest \
+    --header "content-type: application/json" \
+    --header "Authorization: 214ffb**************" \
+    --data "{
+        \"srcAppId\": {
+            \"runtime\": \"codefresh\",
+            \"namespace\": \"membership-staging\",
+            \"name\": \"membership-staging\"
+        },
+        \"destAppId\": {
+            \"runtime\": \"codefresh\",
+            \"namespace\": \"membership-prod\",
+            \"name\": \"membership-prod\"
+        },
+        \"head\": \"main\",
+        \"title\": \"Merge new-accounts\",
+        \"description\": \"Added new accounts and git sources\",
+        \"commitMessage\": \"Merge new-accounts\",
+        \"commitDescription\": \"Approved new accounts and git sources\",
+    }"
+
+```
+### `pullRequest` response example
+
+#### Success
+TBD
+
+
+#### Failure
+TBD
+
+
+
+## Request query parameters
+
+{: .table .table-bordered .table-hover}
+| Parameter    | Description     | 
+| ----------  |  -------- | 
+| `dateRange`       | The time frame for which to send report data. This can be in the from-to format for a custom time frame, or a predefined fixed range.<br>For from-to date ranges, the format is `yyyy-mm-dd`. For example, `?dateRange=2024-04-30&dateRange=2023-08-01`. The from date must be earlier than the to date. <br>For fixed date ranges, use one of the following:<br>- `today`: Today's date.<br>- `Last 7 days`:  <br>- `Last 30 days`: `dateRange=last%203%20month` (NIMA: need to find what are the fixed date ranges supported and how to add them?)|
+| `filter`       |     |
+| `granularity`       |     |
+
+
+<table class="table table-bordered table-hover" style="width: 100%;">
+  <colgroup>
+    <col style="width: 10%;">
+    <col style="width: 70%;">
+    <col style="width: 10%;">
+    <col style="width: 10%;">
+  </colgroup>
+  <thead>
+    <tr>
+      <th style="width: 10%;">Parameter</th>
+      <th style="width: 70%;">Description</th>
+      <th style="width: 10%;">Data Type</th>
+      <th style="width: 10%;">Required/Optional</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td rowspan="4"><code class="highlighter-rouge">dateRange</code></td>
+      <td colspan="3">The application in the source environment to promote through the <code class="highlighter-rouge">runtime</code>, <code class="highlighter-rouge">namespace</code>, and <code class="highlighter-rouge">name</code> key-value pairs.</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">srcAppId.runtime</code>: The name of the GitOps Runtime associated with the source application.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">srcAppId.namespace</code>: The namespace where the source application is deployed.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">srcAppId.name</code>: The name of the source application to be promoted.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td rowspan="4"><code class="highlighter-rouge">destAppId</code></td>
+      <td colspan="3">The application in the destination environment to be promoted through the <code class="highlighter-rouge">runtime</code>, <code class="highlighter-rouge">namespace</code>, and <code class="highlighter-rouge">name</code> key-value pairs.</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">destAppId.runtime</code>: The name of the GitOps Runtime associated with the application in the destination environment.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">destAppId.namespace</code>: The namespace in the destination environment where the application being promoted is deployed.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">destAppId.name</code>: The name of the application in the destination environment to be promoted.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">message</code></td>
+      <td>Applies to <code class="highlighter-rouge">commit</code> promotion actions.<br>The commit message to associate for the commit promotion action.(limits)</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">head</code></td>
+      <td>Applies to <code class="highlighter-rouge">pull request</code> promotion actions.<br>The branch of the application in the destination environment on which to open the PR.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">title</code></td>
+      <td>Applies to <code class="highlighter-rouge">pull request</code> promotion actions.<br>The title of the pull request.</td>
+      <td>String</td>
+      <td>Required</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">description</code></td>
+      <td>Applies to <code class="highlighter-rouge">pull request</code> promotion actions.<br>Additional information describing the pull request.</td>
+      <td>String</td>
+      <td>Optional</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">commitMessage</code></td>
+      <td>Applies to <code class="highlighter-rouge">pull request</code> promotion actions.<br>The commit message when the pull request is approved.<br>If omitted, uses <code class="highlighter-rouge">title</code> instead. </td>
+      <td>String</td>
+      <td>Optional</td>
+    </tr>
+    <tr>
+      <td><code class="highlighter-rouge">commitDescription</code></td>
+      <td>Applies to <code class="highlighter-rouge">pull request</code> promotion actions.<br>Additional information on the commit message when the pull request is approved. </td>
+      <td>String</td>
+      <td>Optional</td>
+    </tr>
+  </tbody>
+</table>
+
+
+
+
+
+