Refactor and clean up API Markdown docs.

This has been pending for several years. Finally, managed to do with GPT-4 "auto" cleaning language and other consistency issues. 90% GPT4, 10% manual hand-wringing. GPT-4 prompt: ``` - Fix grammar, simplify language, and make language and terms consistent. - Remove superfluous language, avoid unncessary "the"s etc. - Change endpoint description in tables that list endpoints, change to terse imperative language. - Parameter / field description in Parameter tables, don't be imperative or use active sentences. Only describe the parameter passively and tersely. - Remove backticks from all headings and table values. - Format markdown tables. - Standardize "data type" columns values into number, string[], string, JSON. - Remove the "parameter type" column from tables. - Wrap ID parameters in URIs in braces. Eg: /lists/list_id to /lists/{list_id} - Add a markdown line above every API path heading that begins with GET, POST, PUT, DELETE. - Leave the lines starting with `#code-` untouched - Do not add new sections, headings, or any new content. Only edit existing content as described above. - Do not remove any sections or any existing content. ```
knadh · Nov 10, 2023 · be4be72 · be4be72
1 parent f8a55f8
commit be4be72
Show file tree

Hide file tree

Showing 10 changed files with 614 additions and 519 deletions.
diff --git a/docs/docs/content/apis/apis.md b/docs/docs/content/apis/apis.md
@@ -44,15 +44,15 @@ All timestamp fields are in the format `2019-01-01T09:00:00.000000+05:30`. The s
 
 ### Common HTTP error codes
 
-| code  | &nbsp;                                                                   |
+| Code  |                                                                          |
 | ----- | ------------------------------------------------------------------------ |
-| `400` | Missing or bad request parameters or values                              |
-| `403` | Session expired or invalidate. Must relogin                              |
-| `404` | Request resource was not found                                           |
-| `405` | Request method (GET, POST etc.) is not allowed on the requested endpoint |
-| `410` | The requested resource is gone permanently                               |
-| `429` | Too many requests to the API (rate limiting)                             |
-| `500` | Something unexpected went wrong                                          |
-| `502` | The backend OMS is down and the API is unable to communicate with it     |
-| `503` | Service unavailable; the API is down                                     |
-| `504` | Gateway timeout; the API is unreachable                                  |
+|  400  | Missing or bad request parameters or values                              |
+|  403  | Session expired or invalidate. Must relogin                              |
+|  404  | Request resource was not found                                           |
+|  405  | Request method (GET, POST etc.) is not allowed on the requested endpoint |
+|  410  | The requested resource is gone permanently                               |
+|  429  | Too many requests to the API (rate limiting)                             |
+|  500  | Something unexpected went wrong                                          |
+|  502  | The backend OMS is down and the API is unable to communicate with it     |
+|  503  | Service unavailable; the API is down                                     |
+|  504  | Gateway timeout; the API is unreachable                                  |
diff --git a/docs/docs/content/apis/campaigns.md b/docs/docs/content/apis/campaigns.md
diff --git a/docs/docs/content/apis/import.md b/docs/docs/content/apis/import.md
@@ -1,22 +1,26 @@
 # API / Import
 
-Method   | Endpoint                                                     | Description
----------|--------------------------------------------------------------|----------------------------------------------------------
-`GET`    | [api/import/subscribers](#get-apiimportsubscribers)          | Gets a import statistics.
-`GET`    | [api/import/subscribers/logs](#get-apiimportsubscriberslogs) | Get a import statistics .
-`POST`   | [api/import/subscribers](#post-apiimportsubscribers)         | Upload a ZIP file or CSV file to bulk import subscribers.
-`DELETE` | [api/import/subscribers](#delete-apiimportsubscribers)       | Stops and deletes a import.
+Method   | Endpoint                                        | Description
+---------|-------------------------------------------------|------------------------------------------------
+GET      | [/api/import/subscribers](#get-apiimportsubscribers) | Retrieve import statistics.
+GET      | [/api/import/subscribers/logs](#get-apiimportsubscriberslogs) | Retrieve import logs.
+POST     | [/api/import/subscribers](#post-apiimportsubscribers) | Upload a file for bulk subscriber import.
+DELETE   | [/api/import/subscribers](#delete-apiimportsubscribers) | Stop and remove an import.
 
+______________________________________________________________________
 
-#### **`GET`** api/import/subscribers
-Gets import status.
+#### GET /api/import/subscribers
 
-##### Example Request 
-```shell 
+Retrieve the status of an import.
+
+##### Example Request
+
+```shell
 curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers'
 ```
 
-##### Example Response 
+##### Example Response
+
 ```json
 {
     "data": {
@@ -28,35 +32,40 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers
 }
 ```
 
-#### **`GET`** api/import/subscribers/logs
-Gets import logs.
+______________________________________________________________________
+
+#### GET /api/import/subscribers/logs
+
+Retrieve logs related to imports.
+
+##### Example Request
 
-##### Example Request 
 ```shell
 curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers/logs'
 ```
 
 ##### Example Response
+
 ```json
 {
     "data": "2020/04/08 21:55:20 processing 'import.csv'\n2020/04/08 21:55:21 imported finished\n"
 }
 ```
 
+______________________________________________________________________
 
+#### POST /api/import/subscribers
 
-#### **`POST`** api/import/subscribers
-Post a CSV (optionally zipped) file to do a bulk import. The request should be a multipart form POST.
-
+Send a CSV (optionally ZIP compressed) file to import subscribers. Use a multipart form POST.
 
 ##### Parameters
 
-Name     | Parameter type | Data type | Required/Optional | Description
----------|----------------|-----------|-------------------|------------------------------------
-`params` | Request body   | String    | Required          | Stringified JSON with import params
-`file`   | Request body   | File      | Required          | File to upload
+| Name   | Type        | Required | Description                              |
+|:-------|:------------|:---------|:-----------------------------------------|
+| params | JSON string | Yes      | Stringified JSON with import parameters. |
+| file   | File        | Yes      | File for upload.                         |
 
-***params*** (JSON string)
+**`params`** (JSON string)
 
 ```json
     {
@@ -67,16 +76,20 @@ Name     | Parameter type | Data type | Required/Optional | Description
     }
 ```
 
+______________________________________________________________________
 
-#### **`DELETE`** api/import/subscribers
-Stops and deletes an import.
+#### DELETE /api/import/subscribers
+
+Stop and delete an ongoing import.
 
 ##### Example Request
+
 ```shell
 curl -u "username:username" -X DELETE 'http://localhost:9000/api/import/subscribers' 
 ```
 
 ##### Example Response
+
 ```json
 {
     "data": {
@@ -86,4 +99,4 @@ curl -u "username:username" -X DELETE 'http://localhost:9000/api/import/subscrib
         "status": "none"
     }
 }
-```
+```
diff --git a/docs/docs/content/apis/lists.md b/docs/docs/content/apis/lists.md
@@ -1,31 +1,37 @@
 # API / Lists
-Method      | Endpoint                                             | Description
-------------|------------------------------------------------------|----------------------------------------------
-`GET`       | [/api/lists](#get-apilists)                          | Gets all lists.
-`GET`       | [/api/lists/:`list_id`](#get-apilistslist_id)        | Gets a single list.
-`POST`      | [/api/lists](#post-apilists)                         | Creates a new list.
-`PUT`       | /api/lists/:`list_id`                                | Modifies a list.
-`DELETE`    | [/api/lists/:`list_id`](#put-apilistslist_id)        | Deletes a list.
 
+| Method | Endpoint                                        | Description               |
+|:-------|:------------------------------------------------|:--------------------------|
+| GET    | [/api/lists](#get-apilists)                     | Retrieve all lists.       |
+| GET    | [/api/lists/{list_id}](#get-apilistslist_id)    | Retrieve a specific list. |
+| POST   | [/api/lists](#post-apilists)                    | Create a new list.        |
+| PUT    | [/api/lists/{list_id}](#put-apilistslist_id)    | Update a list.            |
+| DELETE | [/api/lists/{list_id}](#delete-apilistslist_id) | Delete a list.            |
 
-#### **`GET`** /api/lists
-Gets lists.
+______________________________________________________________________
+
+#### GET /api/lists
+
+Retrieve lists.
 
 ##### Parameters
-Name       | Type   | Required/Optional  | Description
------------|--------|--------------------|-----------------------------------------
-`query`    | string | Optional           | Optional string to search a list by name.
-`order_by` | string | Optional           | Field to sort results by. `name|status|created_at|updated_at`
-`order`    | string | Optional           | `ASC|DESC`Sort by ascending or descending order.
-`page`     | number | Optional           | Page number for paginated results.
-`per_page` | number | Optional           | Results to return per page. Setting this to `all` skips pagination and returns all results.
+
+| Name     | Type      | Required | Description                                                |
+|:---------|:----------|:---------|:-----------------------------------------------------------|
+| query    | string    |          | string for list name search.                               |
+| order_by | string    |          | Sort field. Options: name, status, created_at, updated_at. |
+| order    | string    |          | Sorting order. Options: ASC, DESC.                         |
+| page     | number    |          | Page number for pagination.                                |
+| per_page | number    |          | Results per page. Set to 'all' to return all results.      |
 
 ##### Example Request
+
 ```shell
 curl -u "username:username" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100'
 ```
 
 ##### Example Response
+
 ```json
 {
     "data": {
@@ -62,20 +68,26 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/lists?page=1&per_p
 }
 ```
 
-#### **`GET`** /api/lists/:`list_id`
-Gets a single list.
+______________________________________________________________________
+
+#### GET /api/lists/{list_id}
+
+Retrieve a specific list.
 
 ##### Parameters
-Name      | Parameter type     | Data type   | Required/Optional   | Description
-----------|--------------------|-------------|---------------------|---------------------
-`list_id` | Path parameter     | number      | Required            |  The id value of the list you want to get.
+
+| Name    | Type      | Required | Description                 |
+|:--------|:----------|:---------|:----------------------------|
+| list_id | number    | Yes      | ID of the list to retrieve. |
 
 ##### Example Request
-``` shell
+
+```shell
 curl -u "username:username" -X GET 'http://localhost:9000/api/lists/5'
 ```
 
 ##### Example Response
+
 ```json
 {
     "data": {
@@ -92,23 +104,29 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/lists/5'
 }
 ```
 
-#### **`POST`** /api/lists
-Creates a new list.
+______________________________________________________________________
+
+#### POST /api/lists
+
+Create a new list.
 
 ##### Parameters
-Name    | Parameter type  | Data type   | Required/Optional  | Description
---------|-----------------|-------------|--------------------|----------------
-name    | Request body    | string      | Required           | The new list name.  
-type    | Request body    | string      | Required           | List type, can be set to `private` or `public`.
-optin   | Request body    | string      | Required           | `single` or `double` optin.
-tags    | Request body    | string[]    | Optional           | The tags associated with the list.
+
+| Name  | Type      | Required | Description                             |
+|:------|:----------|:---------|:----------------------------------------|
+| name  | string    | Yes      | Name of the new list.                   |
+| type  | string    | Yes      | Type of list. Options: private, public. |
+| optin | string    | Yes      | Opt-in type. Options: single, double.   |
+| tags  | string\[\]  |          | Associated tags for a list.             |
 
 ##### Example Request
-``` shell
+
+```shell
 curl -u "username:username" -X POST 'http://localhost:9000/api/lists'
 ```
 
 ##### Example Response
+
 ```json
 {
     "data": {
@@ -125,27 +143,33 @@ curl -u "username:username" -X POST 'http://localhost:9000/api/lists'
 null
 ```
 
-#### **`PUT`** /api/lists/`list_id`
-Modifies a list.
+______________________________________________________________________
+
+#### PUT /api/lists/{list_id}
+
+Update a list.
 
 ##### Parameters
-Name      |  Parameter type    | Data type    | Required/Optional     | Description
-----------|--------------------|--------------|-----------------------|-------------------------
-`list_id` | Path parameter     | number       | Required              | The id of the list to be modified.
-name      | Request body       | string       | Optional              | The name which the old name will be modified to.
-type      | Request body       | string       | Optional              | List type, can be set to `private` or `public`.
-optin     | Request body       | string       | Optional              | `single` or `double` optin.
-tags      | Request body       | string[]     | Optional              | The tags associated with the list.
+
+| Name    | Type      | Required | Description                             |
+|:--------|:----------|:---------|:----------------------------------------|
+| list_id | number    | Yes      | ID of the list to update.               |
+| name    | string    |          | New name for the list.                  |
+| type    | string    |          | Type of list. Options: private, public. |
+| optin   | string    |          | Opt-in type. Options: single, double.   |
+| tags    | string\[\]  |          | Associated tags for the list.           |
 
 ##### Example Request
+
 ```shell
 curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \
 --form 'name=modified test list' \
 --form 'type=private'
 ```
 
 ##### Example Response
-``` json
+
+```json
 {
     "data": {
         "id": 5,
@@ -160,3 +184,29 @@ curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \
     }
 }
 ```
+
+______________________________________________________________________
+
+#### DELETE /api/lists/{list_id}
+
+Delete a specific subscriber.
+
+##### Parameters
+
+| Name    | Type      | Required | Description               |
+|:--------|:----------|:---------|:--------------------------|
+| list_id | Number    | Yes      | ID of the list to delete. |
+
+##### Example Request
+
+```shell
+curl -u 'username:password' -X DELETE 'http://localhost:9000/api/lists/1'
+```
+
+##### Example Response
+
+```json
+{
+    "data": true
+}
+```