feat: add documentation for CSV fields and note (#177)

* feat: add documentation for CSV fields and note for reason behind empty csv * refactore: note for empty csv file --------- Co-authored-by: Sonali Tanavade <sonali.tanavade@acrolinx.com>
acrolinx · Sep 20, 2024 · 0ff8686 · 0ff8686
1 parent e850e16
commit 0ff8686
Showing 1 changed file with 66 additions and 60 deletions.
diff --git a/apiary.apib b/apiary.apib
@@ -7251,7 +7251,9 @@ If you exceed the download quota, you'll get a 429 status code. The response wil
 
 ## Get check data [GET /api/v1/reporting/data/checks{?start,end}]
 
-Download check data as a CSV file. You can access the data with cURL.
+Download check data as a CSV file. You can access the data with cURL. 
+
+**Note:** If no data is available, the CSV file will contain headers with zero rows of data. For example, data won't be available if no checks were run in the requested time range.
 
 ```
 curl \
@@ -7260,6 +7262,52 @@ curl \
     -o <replace_file_name>.csv
 ```
 
+### Checks CSV data structure
+|Column name|Data type|Description|Length|
+|----------------|------------|------------|------------|
+|Check ID|string|Unique check ID|36|
+|Check start time|string|Start time of the check in the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, for example, `2022-08-01T23:49:14.627Z`||
+|Language|string|Checking language|255|
+|Scorecard URI|string|Uniform Resource Identifier (URI) of the Scorecard|255|
+|File ID|string|Unique file ID|36|
+|Content reference|string|Acrolinx assigns the file a content reference the first time you run a check. Files with the same content reference are treated as the same file.|36|
+|File path|string|The file's location when it’s first checked|255|
+|File name|string|Name of the file|255|
+|Content ID|string|Unique check ID for batch checks|255|
+|Acrolinx Score|string|Overall Acrolinx Score|255|
+|Acrolinx Score color|string|Color coding of the Acrolinx Score|255|
+|All issues|number|Count of all issues found||
+|Words|number|Number of words in the file||
+|Sentences|number|Number of sentences in the file||
+|Target|string|Name of the Target used|255|
+|Target ID|string|Unique Target ID|36|
+|Content group ID|string|Unique content group ID|36|
+|Content group|string|Name of the content group|1024|
+|User ID|string|Unique user ID|36|
+|Full name|string|Full name of user|255|
+|Integration|string|Integration used to run the check|255|
+|Integration version|string|Integration version|255|
+|Content profile|string|Content profile used|255|
+|Check scope|string|Indicates whether a complete file or a specific selection of content is checked ['check'] or ['check selection'].|16|
+|Custom field {NAME}|string|Custom fields. The number of columns in the CSV file will correspond to the number of custom fields. For example, if there are 10 custom fields, the CSV file will have 10 columns for custom fields.|255|
+|{NAME} goal score|number|Score for a goal. The number of columns in the CSV file will correspond to the number of goal names. For example, if there are 10 goals, the CSV file will have 10 columns for goals.||
+|Clarity goal score|number|Score for the goal Clarity||
+|Consistency goal score|number|Score for the goal Consistency||
+|Correctness goal score|number|Score for the goal Correctness||
+|Inclusive Language goal score|number|Score for the goal Inclusive Language||
+|Scannability goal score|number|Score for the goal Scannability||
+|Terminology goal score|number|Score for the goal Terminology||
+|Tone goal score|number|Score for the goal Tone||
+|{NAME} goal issues|number|Number of Issues found for the goal. The number of columns in the CSV file will correspond to the number of goal names. For example, if there are 10 goals, the CSV file will have 10 columns for goals.||
+|Clarity goal issues|number|Number of Issues found for the goal Clarity||
+|Consistency goal issues|number|Number of Issues found for the goal Consistency||
+|Correctness goal issues|number|Number of Issues found for the goal Correctness||
+|Inclusive Language goal issues|number|Number of Issues found for the goal Inclusive Language||
+|Scannability goal issues|number|Number of Issues found for the goal Scannability||
+|Terminology goal issues|number|Number of Issues found for the goal Terminology||
+|Tone goal issues|number|Number of issues found for the goal Tone||
+|{NAME} metric score|number|Metrics suffix by actual name. If there are 10 metrics, the CSV will have 10 columns for metrics suffix by name of the metric||
+
 + Request
 
     + Headers
@@ -7381,54 +7429,11 @@ curl \
             "message": "Something went wrong. Try again or contact Acrolinx Support."
         } 
 
-+ Attributes (object)
-    + Checks CSV data structure (object)
-        + Check ID (string) - Unique check ID
-        + Check start time (string) - Start time of the check in the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, for example, `2022-08-01T23:49:14.627Z` 
-        + Language (string) - Checking language 
-        + Scorecard URI (string) - Uniform Resource Identifier (URI) of the Scorecard 
-        + File ID (string) - Unique file ID 
-        + Content reference (string) - Acrolinx assigns the file a content reference the first time you run a check. Files with the same content reference are treated as the same file.
-        + File path (string) - The file's location when it’s first checked 
-        + File name (string) - Name of the file 
-        + Content ID (string) - Unique check ID for batch checks 
-        + Acrolinx Score (number) - Overall Acrolinx Score 
-        + Acrolinx Score color (string) - Color coding of the Acrolinx Score 
-        + All issues (number) - Count of all issues found 
-        + Words (number) - Number of words in the file 
-        + Sentences (number) - Number of sentences in the file 
-        + Target (number) - Name of the Target used 
-        + Target ID (string) - Unique Target ID 
-        + Content group ID (string) - Unique content group ID 
-        + Content group (string) - Name of the content group 
-        + User ID (string) - Unique user ID 
-        + Full name (string) - Full name of user 
-        + Integration (string) - Integration used to run the check 
-        + Integration version (string) - Integration version 
-        + Content profile (string) - Content profile used 
-        + Check scope (string) - Indicates whether a complete file or a specific selection of content is checked ['check' | 'check selection'].
-        + Custom field {NAME} (string) - Custom fields. The number of columns in the CSV file will correspond to the number of custom fields. For example, if there are 10 custom fields, the CSV file will have 10 columns for custom fields.
-        + {NAME} goal score (number) - Score for a goal. The number of columns in the CSV file will correspond to the number of goal names. For example, if there are 10 goals, the CSV file will have 10 columns for goals.
-        + Clarity goal score (number) - Score for the goal Clarity  
-        + Consistency goal score (number) - Score for the goal Consistency 
-        + Correctness goal score (number) - Score for the goal Correctness 
-        + Inclusive Language goal score (number) - Score for the goal Inclusive Language 
-        + Scannability goal score (number) - Score for the goal Scannability 
-        + Terminology goal score (number) - Score for the goal Terminology   
-        + Tone goal score (number) - Score for the goal Tone 
-        + {NAME} goal issues (number) - Number of Issues found for the goal. The number of columns in the CSV file will correspond to the number of goal names. For example, if there are 10 goals, the CSV file will have 10 columns for goals.
-        + Clarity goal issues (number) - Number of Issues found for the goal Clarity 
-        + Consistency goal issues (number) - Number of Issues found for the goal Consistency 
-        + Correctness goal issues (number) - Number of Issues found for the goal Correctness 
-        + Inclusive Language goal issues  (number) - Number of Issues found for the goal Inclusive Language 
-        + Scannability goal issues (number) - Number of Issues found for the goal Scannability 
-        + Terminology goal issues (number) - Number of Issues found for the goal Terminology 
-        + Tone goal issues (number) - Number of issues found for the goal Tone 
-        + {NAME} metric score (number) - Metrics suffix by actual name. If there are 10 metrics, the CSV will have 10 columns for metrics suffix by name of the metric
-
 ## Get issues data [GET /api/v1/reporting/data/issues{?start,end}]
 
-Download issue data as a CSV file. You can access the data with cURL.
+Download issue data as a CSV file. You can access the data with cURL. 
+
+**Note:** If no data is available, the CSV file will contain headers with zero rows of data. For example, data won't be available if no checks were run in the requested time range.
 
 ```
 curl \
@@ -7437,6 +7442,19 @@ curl \
     -o <replace_file_name>.csv
 ```
 
+### Issues CSV data structure
+|Column name|Data type|Description|Length|
+|----------------|------------|------------|------------|
+|Check ID|string|Unique check ID|36|
+|Date|string|Date when the issue was found. Shown in the format `yyyy-MM-dd`, for example, `2022-01-20`||
+|Context|string|Sentence or paragraph where the issue occurred|1024|
+|Issue|string|Content that Acrolinx highlighted|255|
+|Structural context|string|Structural location where the issue occurred in the file|1024|
+|Guideline ID|string|Unique ID of the guideline|255|
+|Guideline name|string|Name of the guideline|255|
+|Language|string|Checking language|255|
+|Issue type|string|Type of issue|20|
+
 + Request
 
     + Headers
@@ -7555,16 +7573,4 @@ curl \
         {
             "code": 500,
             "message": "Something went wrong. Try again or contact Acrolinx Support."
-        } 
-
-+ Attributes (object)
-    + Issues CSV data structure (object)
-        + Check ID (string) - Unique check ID
-        + Date (string) - Date when the issue was found. Shown in the format `yyyy-MM-dd`, for example, `2022-01-20` 
-        + Context (string) - Sentence or paragraph where the issue occurred
-        + Issue (string) - Content that Acrolinx highlighted 
-        + Structural context (string) - Structural location where the issue occurred in the file 
-        + Guideline ID (string) - Unique ID of the guideline  
-        + Guideline name (string) - Name of the guideline 
-        + Language (string) - Checking language 
-        + Issue type (string) - Type of issue 
+        }