Clarify which endpoints return committed / pending transactions

api/Makefile

@@ -29,7 +29,7 @@ test-api-spec-v1:
 	$(call test_api_spec,spec.yaml)
 
 serve:
-	cd doc && python -m http.server 8888
+	cd doc && python3 -m http.server 8888
 
 define test_api_spec
 	- pkill aptos-node

api/doc/spec.json

@@ -51,7 +51,7 @@
           "Accounts"
         ],
         "summary": "Get account",
-        "description": "Retrieves high level information about an account such as its sequence number and\nauthentication key\n\nReturns a 404 if the account doesn't exist",
+        "description": "Return the authentication key and the sequence number for an account\naddress. Optionally, a ledger version can be specified. If the ledger\nversion is not specified in the request, the latest ledger version is used.",
         "parameters": [
           {
             "name": "address",
@@ -6200,7 +6200,7 @@
           "Transactions"
         ],
         "summary": "Get transactions",
-        "description": "Retrieve on-chain committed transactions. The page size and start can be provided to\nget a specific sequence of transactions.\n\nIf the version has been pruned, then a 410 will be returned",
+        "description": "Retrieve on-chain committed transactions. The page size and start ledger version\ncan be provided to get a specific sequence of transactions.\n\nIf the version has been pruned, then a 410 will be returned.\n\nTo retrieve a pending transaction, use /transactions/by_hash.",
         "parameters": [
           {
             "name": "start",

api/doc/spec.yaml

@@ -32,10 +32,9 @@ paths:
       - Accounts
       summary: Get account
       description: |-
-        Retrieves high level information about an account such as its sequence number and
-        authentication key
-
-        Returns a 404 if the account doesn't exist
+        Return the authentication key and the sequence number for an account
+        address. Optionally, a ledger version can be specified. If the ledger
+        version is not specified in the request, the latest ledger version is used.
       parameters:
       - name: address
         schema:
@@ -4639,10 +4638,12 @@ paths:
       - Transactions
       summary: Get transactions
       description: |-
-        Retrieve on-chain committed transactions. The page size and start can be provided to
-        get a specific sequence of transactions.
+        Retrieve on-chain committed transactions. The page size and start ledger version
+        can be provided to get a specific sequence of transactions.
+
+        If the version has been pruned, then a 410 will be returned.
 
-        If the version has been pruned, then a 410 will be returned
+        To retrieve a pending transaction, use /transactions/by_hash.
       parameters:
       - name: start
         schema:

api/src/accounts.rs

@@ -41,10 +41,9 @@ pub struct AccountsApi {
 impl AccountsApi {
     /// Get account
     ///
-    /// Retrieves high level information about an account such as its sequence number and
-    /// authentication key
-    ///
-    /// Returns a 404 if the account doesn't exist
+    /// Return the authentication key and the sequence number for an account 
+    /// address. Optionally, a ledger version can be specified. If the ledger
+    /// version is not specified in the request, the latest ledger version is used.
     #[oai(
         path = "/accounts/:address",
         method = "get",

api/src/transactions.rs

@@ -137,10 +137,12 @@ pub struct TransactionsApi {
 impl TransactionsApi {
     /// Get transactions
     ///
-    /// Retrieve on-chain committed transactions. The page size and start can be provided to
-    /// get a specific sequence of transactions.
+    /// Retrieve on-chain committed transactions. The page size and start ledger version
+    /// can be provided to get a specific sequence of transactions.
     ///
-    /// If the version has been pruned, then a 410 will be returned
+    /// If the version has been pruned, then a 410 will be returned.
+    ///
+    /// To retrieve a pending transaction, use /transactions/by_hash.
     #[oai(
         path = "/transactions",
         method = "get",

ecosystem/typescript/sdk/src/generated/services/AccountsService.ts

@@ -19,10 +19,9 @@ export class AccountsService {
 
     /**
      * Get account
-     * Retrieves high level information about an account such as its sequence number and
-     * authentication key
-     *
-     * Returns a 404 if the account doesn't exist
+     * Return the authentication key and the sequence number for an account
+     * address. Optionally, a ledger version can be specified. If the ledger
+     * version is not specified in the request, the latest ledger version is used.
      * @param address Address of account with or without a `0x` prefix
      * @param ledgerVersion Ledger version to get state of account
      *

ecosystem/typescript/sdk/src/generated/services/TransactionsService.ts

@@ -22,10 +22,12 @@ export class TransactionsService {
 
     /**
      * Get transactions
-     * Retrieve on-chain committed transactions. The page size and start can be provided to
-     * get a specific sequence of transactions.
+     * Retrieve on-chain committed transactions. The page size and start ledger version
+     * can be provided to get a specific sequence of transactions.
      *
-     * If the version has been pruned, then a 410 will be returned
+     * If the version has been pruned, then a 410 will be returned.
+     *
+     * To retrieve a pending transaction, use /transactions/by_hash.
      * @param start Ledger version to start list of transactions
      *
      * If not provided, defaults to showing the latest transactions