From 1a6d9e76d3fc4872c1e29eb74323e38b7cb3ad50 Mon Sep 17 00:00:00 2001
From: Xiao Li <ilx@fb.com>
Date: Fri, 24 Sep 2021 12:53:47 -0700
Subject: [PATCH] [api] first draft version api blueprint document for
 implemented API

Closes: #9262
---
 api/README.md      |  21 ++++++
 api/blueprint.apib | 181 +++++++++++++++++++++++++++++++++++++++++++++
 api/dredd.yml      |  32 ++++++++
 3 files changed, 234 insertions(+)
 create mode 100644 api/blueprint.apib
 create mode 100644 api/dredd.yml

diff --git a/api/README.md b/api/README.md
index 514147e0e68bd..638b3066eadce 100644
--- a/api/README.md
+++ b/api/README.md
@@ -2,11 +2,32 @@
 
 This module provides REST API for client applications to query the Diem blockchain.
 
+The [API specification](blueprint.apib) is documented in [API Blueprint](https://apiblueprint.org) format.
 
 ## Testing
 
+### Integration/Smoke Test
+
 Run integration/smoke tests in `testsuite/smoke-test`
 
 ```
 cargo test --test "forge" "api::"
 ```
+
+### API Specification Test
+
+* Build diem-node: `cargo build -p diem-node`
+* Install [dredd](https://dredd.org/en/latest/)
+* Run `dredd` inside 'api' directory.
+
+
+### Render API into HTML Document
+
+
+For example, use [snowboard](https://github.com/bukalapak/snowboard)
+
+```
+npm install -g snowboard
+snowboard http blueprint.apib
+open http://localhost:8088
+```
diff --git a/api/blueprint.apib b/api/blueprint.apib
new file mode 100644
index 0000000000000..dd4f93cec290a
--- /dev/null
+++ b/api/blueprint.apib
@@ -0,0 +1,181 @@
+FORMAT: 1A
+
+# Diem API
+
+This module provides REST API for client applications to query the Diem blockchain.
+
+# Group LedgerInfo
+
+## GET /
+
+Get latest ledger info.
+
+- Response 200 (application/json)
+  - Attributes (LedgerInfo)
+
+# Group Accounts
+
+Accounts API for querying data under an account address.
+
+## Account Resources [/accounts/{address}/resources]
+
+- Parameters
+  - address: 0xdd (Address, required)
+
+### Get Account Resources [GET]
+
+- Response 200 (application/json)
+  - Attributes (array[MoveResource], fixed-type)
+
+## Account Modules [/accounts/{address}/modules]
+
+- Parameters
+  - address: 0x1 (Address, required)
+
+### Get Account Modules [GET]
+
+- Response 200 (application/json)
+  - Attributes (array[MoveModule], fixed-type)
+
+# Data Structures
+
+## LedgerInfo
+
+- `chain_id`: 4 (number, required) - The blockchain chain id
+- `ledger_version`: 52635485 (U64, required) - The version of the latest transaction in the ledger / latest block on-chain
+- `ledger_timestamp`: 1632507671675208 (U64, required) - The timestamp of the ledger version in microseconds
+
+## MoveResource
+
+- type (MoveTypeStruct, required) - resource data type, it is also access path of the resource on server.
+- value (object, required) - resource data, field name map to field value, use `type` data to decode.
+
+## MoveModule
+
+- address: 0x1 (Address, required)
+- name: Diem (string, required)
+- friends (array[MoveModuleId], fixed-type, required)
+- exposed_functions (array[MoveFunction], fixed-type, required)
+- structs (array[MoveStruct], fixed-type, required)
+
+## MoveStruct
+
+- name: Diem (string)
+- `is_native`: false (boolean)
+- abilities (array[MoveAbility], fixed-type, required)
+- `generic_type_params` (array[MoveStructGenericTypeParam], fixed-type, required)
+- fields (array[MoveStructField], fixed-type, required)
+
+## MoveStructField
+
+- name: value (string, required)
+- type (MoveType, required)
+
+## MoveStructGenericTypeParam
+
+- constraints (array[MoveAbility], fixed-type, required)
+- `is_phantom`: false (boolean, required)
+
+## MoveFunction
+
+- name: mint (string, required) - Move function name
+- visibility: script (MoveFunctionVisibility, required) - Move function visibility
+- `generic_type_params` (array[MoveFunctionGenericTypeParam], fixed-type, required)
+- params (array[MoveType], fixed-type, required)
+- return (array[MoveType], fixed-type, required)
+
+## MoveFunctionVisibility (enum)
+
+- public
+- private
+- script
+- friend
+
+## MoveFunctionGenericTypeParam
+
+- constraints (array[MoveAbility], fixed-type, required)
+
+## MoveAbility (enum)
+
+- copy
+- drop
+- store
+- key
+
+## MoveModuleId
+
+- address: 0x1 (Address)
+- name: Diem (string)
+
+## MoveType (enum)
+
+- (MoveTypeBool)
+- (MoveTypeU8)
+- (MoveTypeU64)
+- (MoveTypeU128)
+- (MoveTypeAddress)
+- (MoveTypeSigner)
+- (MoveTypeVector)
+- (MoveTypeStruct)
+- (MoveTypeGenericTypeParam)
+- (MoveTypeReference)
+
+## MoveTypeBool
+
+- type: bool (fixed, required)
+
+## MoveTypeU8
+
+- type: u8 (fixed, required)
+
+## MoveTypeU64
+
+- type: u64 (fixed, required)
+
+## MoveTypeU128
+
+- type: u128 (fixed, required)
+
+## MoveTypeAddress
+
+- type: address (fixed, required)
+
+## MoveTypeSigner
+
+- type: signer (fixed, required)
+
+## MoveTypeVector
+
+- type: vector (fixed, required)
+- items (MoveType, required) - Type of the vector / array items.
+
+## MoveTypeStruct
+
+- type: struct (fixed, required)
+- address: 0x1 (Address, required)
+- module: Diem (required) - module identifier / name
+- name: Diem (required) - struct name
+- `generic_type_params` (array[MoveType], fixed-type, required) - generic type parameters defined for the struct.
+
+## MoveTypeGenericTypeParam
+
+- type: `generic_type_param` (fixed, required)
+- index: 0 (number, required) - The index of the generic type parameter referenced to the field `generic_type_params` in the `MoveTypeStruct`
+
+## MoveTypeReference
+
+- type: reference (fixed, required)
+- mutable: false (boolean, required) - whether the reference is mutable or immutable.
+- to (MoveType, required) - The `MoveType` referenced to.
+
+## Address (string)
+
+Hex-encoded account address with `0x` prefix and trimmed leading zeros.
+
+## U64 (string)
+
+Unsigned integer 64. Due to the JSON / JS limit (see rfc8259), we renders uint64 as string in JSON.
+
+## U128 (string)
+
+Unsigned integer 128. Due to the JSON / JS limit (see rfc8259), we renders uint128 as string in JSON.
diff --git a/api/dredd.yml b/api/dredd.yml
new file mode 100644
index 0000000000000..16971d218e000
--- /dev/null
+++ b/api/dredd.yml
@@ -0,0 +1,32 @@
+color: true
+dry-run: null
+hookfiles: null
+language: nodejs
+require: null
+server: ./../target/debug/diem-node --test
+server-wait: 3
+init: false
+custom: {}
+names: false
+only: []
+reporter: []
+output: []
+header: []
+sorted: false
+user: null
+inline-errors: false
+details: false
+method: []
+loglevel: warning
+path: []
+hooks-worker-timeout: 5000
+hooks-worker-connect-timeout: 1500
+hooks-worker-connect-retry: 500
+hooks-worker-after-connect-wait: 100
+hooks-worker-term-timeout: 5000
+hooks-worker-term-retry: 500
+hooks-worker-handler-host: 127.0.0.1
+hooks-worker-handler-port: 61321
+config: ./dredd.yml
+blueprint: blueprint.apib
+endpoint: 'http://localhost:8081/'