Skip to content

Commit ef830d0

Browse files
aorumbayevaorumbayev
committed
feat: initial support for oas spec based http clients
chore: adding more structure to api folder; automating generation of py|ts clients chore: refining stock template to leverage pytest over unittest and auto generate valid baseline tests chore: removing auto generated tests as they are too cumbersome to modify - Instead setting up a structure for custom mustache files implementing manually written tests given that each end point (total around 55) often requires complex state setup - For the time being the only test established is the test for sending raw transactions chore: refining base python tests; fixing typescript template chore: add basic txn params tests chore: refine python transaction tests chore: typescript client tweaks and initial tests docs: initial doc on api folder and oas generators chore: adding default pr and issue templates chore: refning docs chore: moving python ffi improvements to separate pr; adding basic ci for oas clients chore: expose raw response context (#67) chore: addressing pr comments chore: merge conflict fixes chore: addressing pr comments
1 parent 7b66a50 commit ef830d0

File tree

101 files changed

+23167
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

101 files changed

+23167
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: "\U0001F41C Bug report"
3+
about: Report a reproducible bug.
4+
title: ''
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
### Subject of the issue
10+
11+
<!-- Describe your issue here. -->
12+
13+
### Your environment
14+
15+
<!--
16+
* Please provide the output of `algokit doctor` command response,
17+
* This will give us a good idea about your environment
18+
-->
19+
20+
### Steps to reproduce
21+
22+
1.
23+
2.
24+
25+
### Expected behaviour
26+
27+
### Actual behaviour

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: "\U0001F514 Feature Request"
3+
about: Suggestions for how we can improve the algorand platform.
4+
title: ''
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Problem
10+
11+
<!-- What is the problem that we’re trying to solve? -->
12+
13+
## Solution
14+
15+
<!-- Do you have a potential/suggested solution? Document more than one if possible. -->
16+
17+
### Proposal
18+
19+
<!-- Describe the solution you’d like in detail. -->
20+
21+
### Pros and Cons
22+
23+
<!-- What are the advantages and disadvantages of this solution? -->
24+
25+
## Dependencies
26+
27+
<!-- Does the solution have any team or design dependencies? -->

‎.github/pull_request_template.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Fixes #
2+
3+
## Proposed Changes
4+
5+
-
6+
-
7+
-

‎.github/workflows/api_clients_ci.yml‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
name: API Clients CI
2+
3+
on:
4+
pull_request:
5+
branches: [ main ]
6+
paths:
7+
- 'api/**'
8+
- '.github/workflows/api_clients_ci.yml'
9+
workflow_dispatch:
10+
11+
env:
12+
CRATE: algokit_transact
13+
14+
jobs:
15+
setup:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Setup Bun
21+
uses: oven-sh/setup-bun@v2
22+
with:
23+
bun-version: latest
24+
25+
- name: Setup api tools
26+
working-directory: api
27+
run: bun install
28+
29+
- name: Generate TypeScript client
30+
working-directory: api
31+
run: bun run scripts/generate-algod-clients.ts --target typescript
32+
33+
- name: Upload TypeScript client
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: algokit-algod-api-ts
37+
path: api/api_clients/typescript
38+
retention-days: 1
39+
40+
- name: Generate Python client
41+
working-directory: api
42+
run: bun run scripts/generate-algod-clients.ts --target python
43+
44+
- name: Upload Python client
45+
uses: actions/upload-artifact@v4
46+
with:
47+
name: algokit-algod-api-py
48+
path: api/api_clients/python
49+
retention-days: 1
50+
51+
algokit-algod-api-ts:
52+
needs: setup
53+
runs-on: ubuntu-latest
54+
steps:
55+
- uses: actions/checkout@v4
56+
57+
- uses: dtolnay/rust-toolchain@master
58+
with:
59+
toolchain: 1.85.0
60+
61+
- name: Setup Bun
62+
uses: oven-sh/setup-bun@v2
63+
with:
64+
bun-version: latest
65+
66+
- name: Download TypeScript client
67+
uses: actions/download-artifact@v4
68+
with:
69+
name: algokit-algod-api-ts
70+
path: api/api_clients/typescript
71+
72+
- name: Install AlgoKit
73+
run: pipx install algokit
74+
75+
- name: Start localnet
76+
run: algokit localnet start
77+
78+
- name: Setup Node.js
79+
uses: actions/setup-node@v4
80+
with:
81+
node-version: 20
82+
cache: 'npm'
83+
cache-dependency-path: 'api/api_clients/typescript/package.json'
84+
85+
- name: Build TypeScript ffi package
86+
run: bun scripts/build ${{ env.CRATE }} typescript
87+
88+
- name: Test TypeScript client
89+
working-directory: api/api_clients/typescript
90+
run: |
91+
npm install
92+
npm run test
93+
94+
algokit-algod-api-py:
95+
needs: setup
96+
runs-on: ubuntu-latest
97+
steps:
98+
- uses: actions/checkout@v4
99+
100+
- uses: dtolnay/rust-toolchain@master
101+
with:
102+
toolchain: 1.85.0
103+
104+
- name: Download Python client
105+
uses: actions/download-artifact@v4
106+
with:
107+
name: algokit-algod-api-py
108+
path: api/api_clients/python
109+
110+
- name: Install AlgoKit
111+
run: pipx install algokit
112+
113+
- name: Start localnet
114+
run: algokit localnet start
115+
116+
- name: Install poetry
117+
run: pipx install poetry
118+
119+
- name: Setup Python
120+
uses: actions/setup-python@v5
121+
with:
122+
python-version: '3.10'
123+
124+
- name: Test Python client
125+
working-directory: api/api_clients/python
126+
run: |
127+
poetry install
128+
poetry run pytest

‎api/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
api_clients/python/
2+
api_clients/typescript/

‎api/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Algorand API Tools
2+
3+
This package contains tools for working with the Algorand API specifications and generating HTTP client libraries.
4+
5+
## Prerequisites
6+
7+
- [Bun](https://bun.sh/) - JavaScript runtime and package manager
8+
- [OpenJDK](https://adoptium.net/) - Java Development Kit
9+
10+
## Setup
11+
12+
```bash
13+
# Install dependencies
14+
bun install
15+
```
16+
17+
## Available Scripts
18+
19+
### Convert OpenAPI 2.0 to OpenAPI 3.0
20+
21+
Converts the Algod OpenAPI 2.0 spec to OpenAPI 3.0:
22+
23+
```bash
24+
bun run convert-openapi
25+
```
26+
27+
The converted spec will be available at `specs/algod.oas3.json`.
28+
29+
### Generate API Clients
30+
31+
Generates TypeScript and Python API clients based on the OpenAPI spec:
32+
33+
```bash
34+
bun run generate-algod-clients
35+
# or
36+
bun run scripts/generate-algod-clients.ts --target {python|typescript}
37+
```
38+
39+
The generated clients will be available in the `../generated/` directory:
40+
41+
- `../generated/typescript/` - TypeScript client
42+
- `../generated/python/` - Python client
43+
44+
## OpenAPI Specs for algorand apis
45+
46+
## Algod
47+
48+
The `algod.oas2.json` is taken directly from [go-algorand](https://github.com/algorand/go-algorand/blob/master/daemon/algod/api/algod.oas2.json). The script under [scripts/convert-openapi.ts](scripts/convert-openapi.ts) is used to convert the spec to OpenAPI 3.0 via [swagger converter](https://converter.swagger.io/) endpoint. The current approach is to manually edit and tweak the algod.oas2.json fixing known issues on a spec from go-algorand, then use the openapi-generator-cli to generate clients on the v3 spec. OpenAPI v3 is preferred for client generation as it offers enhanced schema features, better component reusability, and improved type definitions compared to v2. Additionally, most modern code generators like openapi-generator-cli provide better support and more accurate code generation when working with v3 specifications.
49+
50+
## OpenAPI Generator Configuration
51+
52+
The client generation is configured with the following options:
53+
54+
### TypeScript Client
55+
56+
- Package name: `@algorandfoundation/algokit-algod-api-ts`
57+
- ES6 support: true
58+
- Manually refined tsconfig setup to build cjs, esm clients along with browser support.
59+
- Custom tests defined in `oas_templates/typescript/custom-tests/` that implement tests for initial batch of transaction endpoints. More endpoint tests are to be added in the future.
60+
61+
### Python Client
62+
63+
- Package name: `algokit_algod_api_py`
64+
- Ignoring various unneeded supporting files like tox.ini, git_push.sh, etc.
65+
- Various improvements to make auto generated code compatible with poetry and more modern python conventions and practices.
66+
- Custom tests defined in `oas_templates/python/custom-tests/` that implement tests for initial batch of transaction endpoints. More endpoint tests are to be added in the future.

‎packages/python/algokit_transact/algokit_transact/py.typed‎ renamed to ‎api/api_clients/python/.gitkeep‎

File renamed without changes.

‎api/api_clients/typescript/.gitkeep‎

Whitespace-only changes.

‎api/bun.lockb‎

54.8 KB
Binary file not shown.

‎api/notes.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Algorand API Categorization
2+
3+
| Category | Endpoints |
4+
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5+
| **Transactions** | - PendingTransactionInformation<br>- GetPendingTransactions<br>- GetPendingTransactionsByAddress<br>- RawTransaction<br>- RawTransactionAsync<br>- SimulateTransaction<br>- TransactionParams<br>- GetTransactionProof<br>- GetLedgerStateDeltaForTransactionGroup<br>- GetTransactionGroupLedgerStateDeltasForRound |
6+
| **Accounts** | - AccountInformation<br>- AccountApplicationInformation<br>- AccountAssetInformation<br>- AccountAssetsInformation |
7+
| **Applications (Smart Contracts)** | - GetApplicationByID<br>- GetApplicationBoxByName<br>- GetApplicationBoxes<br>- TealCompile<br>- TealDisassemble<br>- TealDryrun |
8+
| **Assets** | - GetAssetByID |
9+
| **Blocks & Ledger** | - GetBlock<br>- GetBlockHash<br>- GetBlockLogs<br>- GetBlockTxids<br>- WaitForBlock<br>- GetLedgerStateDelta<br>- GetSupply<br>- GetStateProof<br>- GetLightBlockHeaderProof |
10+
| **Node Management** | - GetStatus<br>- GetVersion<br>- GetReady<br>- HealthCheck<br>- ShutdownNode<br>- GetConfig<br>- Metrics<br>- AbortCatchup<br>- StartCatchup<br>- SetSyncRound<br>- UnsetSyncRound<br>- GetSyncRound |
11+
| **Participation Keys** | - AddParticipationKey<br>- AppendKeys<br>- DeleteParticipationKeyByID<br>- GenerateParticipationKeys<br>- GetParticipationKeyByID<br>- GetParticipationKeys |
12+
| **Debug & Development** | - ExperimentalCheck<br>- GetBlockTimeStampOffset<br>- SetBlockTimeStampOffset<br>- GetDebugSettingsProf<br>- PutDebugSettingsProf<br>- SwaggerJSON |
13+
| **Genesis** | - GetGenesis |

0 commit comments

Comments
 (0)