Skip to content

Commit 4181075

Browse files
karlspacekarlspace
authored
Merge pull request #4 from bauer-group/feature-20251009
Seamless support for NocoDB API v2 and v3
2 parents d312b0c + f0dea7c commit 4181075

30 files changed

+20428
-121
lines changed

‎CHANGELOG.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,39 @@
22

33
<!-- version list -->
44

5+
## Unreleased
6+
7+
### Features
8+
9+
- **API Version Support**: Add seamless support for NocoDB API v2 and v3
10+
- Implement `api_version` parameter for client initialization (default: "v2")
11+
- Add automatic parameter conversion between v2 and v3 formats
12+
- Pagination: `offset/limit` (v2) ↔ `page/pageSize` (v3)
13+
- Sort: string format (v2) ↔ JSON array format (v3)
14+
- Operators: automatic conversion (e.g., `ne` → `neq`)
15+
- Implement `BaseIdResolver` with caching for v3 API base_id resolution
16+
- Add v2/v3 support to all Data API methods (14 methods)
17+
- Add v2/v3 support to all Meta API methods (29 methods)
18+
- Update `NocoDBTable` wrapper to support `base_id` parameter
19+
- Full backward compatibility maintained for existing v2 code
20+
21+
### Documentation
22+
23+
- Add comprehensive API Version Guide ([docs/API_VERSION_GUIDE.md](docs/API_VERSION_GUIDE.md))
24+
- Add Data API v2/v3 usage examples ([examples/api_version_example.py](examples/api_version_example.py))
25+
- Add Meta API v2/v3 usage examples ([examples/meta_api_version_example.py](examples/meta_api_version_example.py))
26+
- Update README.template.md with API version support documentation
27+
- Add OpenAPI v2 and v3 specification files to docs directory
28+
29+
### Tests
30+
31+
- Add 88 new unit tests for v2/v3 functionality
32+
- 52 tests for PathBuilder and QueryParamAdapter
33+
- 15 tests for BaseIdResolver
34+
- 21 integration tests for version switching
35+
- Update existing tests for new `base_id` parameter
36+
- All 454 tests passing with full coverage
37+
538
## v1.2.0 (2025-10-09)
639

740
### Bug Fixes

‎docs/API_COMPARISON_README.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# NocoDB API v2 to v3 Comparison Documentation
2+
3+
This directory contains comprehensive analysis and migration guides for the NocoDB API v2 to v3 transition.
4+
5+
## 📚 Documentation Index
6+
7+
### 1. **Quick Start: Migration Guide** ⭐
8+
**File:** [`API_V2_V3_MIGRATION_GUIDE.md`](./API_V2_V3_MIGRATION_GUIDE.md)
9+
10+
**Use this if you need:** Practical migration steps, code examples, and quick reference tables.
11+
12+
**Contents:**
13+
- Critical breaking changes by priority
14+
- Code migration examples for most-used endpoints
15+
- Implementation strategies (adapter pattern, query parameter conversion)
16+
- Base ID resolution strategies
17+
- Testing checklist
18+
- Common pitfalls and solutions
19+
- Quick reference tables
20+
- Timeline estimates and risk assessment
21+
22+
**Best for:** Developers actively migrating code from v2 to v3.
23+
24+
---
25+
26+
### 2. **Comprehensive Comparison Report**
27+
**File:** [`NOCODB_API_V2_V3_COMPARISON.md`](./NOCODB_API_V2_V3_COMPARISON.md)
28+
29+
**Use this if you need:** Deep understanding of all architectural changes and endpoint differences.
30+
31+
**Contents:**
32+
- Executive summary with statistics
33+
- Major architectural changes explained
34+
- Complete list of removed endpoints (137 from Meta API)
35+
- Complete list of new endpoints (36 in Data API)
36+
- Critical breaking changes tables
37+
- Migration path analysis
38+
- Detailed implementation strategy
39+
- Version detection code
40+
- Base ID resolver implementation
41+
42+
**Best for:** Architects planning the migration strategy and understanding scope.
43+
44+
---
45+
46+
### 3. **Schema & Parameter Analysis**
47+
**File:** [`NOCODB_API_SCHEMA_COMPARISON.md`](./NOCODB_API_SCHEMA_COMPARISON.md)
48+
49+
**Use this if you need:** Detailed query parameter and response schema changes.
50+
51+
**Contents:**
52+
- Query parameter comparison for list records
53+
- Pagination changes (offset/limit → page/pageSize)
54+
- Sort format changes (string → JSON)
55+
- Response schema structures
56+
- Error response format differences
57+
- Field naming conventions
58+
59+
**Best for:** Developers implementing query parameter conversion and response parsing.
60+
61+
---
62+
63+
### 4. **Initial Comparison Report**
64+
**File:** [`API_COMPARISON_V2_V3.md`](./API_COMPARISON_V2_V3.md)
65+
66+
**Use this if you need:** High-level overview and endpoint categorization.
67+
68+
**Contents:**
69+
- Statistics (endpoints removed/added)
70+
- Endpoints categorized by type (Table, Record, View, etc.)
71+
- Basic breaking changes summary
72+
- Simple implementation recommendations
73+
74+
**Best for:** Initial assessment and presenting to stakeholders.
75+
76+
---
77+
78+
## 🚀 Quick Navigation by Use Case
79+
80+
### "I need to understand what changed"
81+
→ Start with [`NOCODB_API_V2_V3_COMPARISON.md`](./NOCODB_API_V2_V3_COMPARISON.md) (Section: Executive Summary)
82+
83+
### "I need to migrate record operations"
84+
→ Go to [`API_V2_V3_MIGRATION_GUIDE.md`](./API_V2_V3_MIGRATION_GUIDE.md) (Section: Most Used Endpoints)
85+
86+
### "I need to understand pagination changes"
87+
→ Go to [`NOCODB_API_SCHEMA_COMPARISON.md`](./NOCODB_API_SCHEMA_COMPARISON.md) (Section: List Records Query Parameters)
88+
89+
### "I need implementation code examples"
90+
→ Go to [`API_V2_V3_MIGRATION_GUIDE.md`](./API_V2_V3_MIGRATION_GUIDE.md) (Section: Implementation Strategy)
91+
92+
### "I need to handle baseId resolution"
93+
→ Go to [`API_V2_V3_MIGRATION_GUIDE.md`](./API_V2_V3_MIGRATION_GUIDE.md) (Section: Base ID Resolution)
94+
95+
### "I need a complete list of endpoint changes"
96+
→ Go to [`NOCODB_API_V2_V3_COMPARISON.md`](./NOCODB_API_V2_V3_COMPARISON.md) (Sections: Removed/New Endpoints)
97+
98+
---
99+
100+
## ⚠️ Critical Findings Summary
101+
102+
### 1. API File Role Reversal
103+
**v2 and v3 have INVERTED their API file definitions!**
104+
105+
- v2's "Meta API" (137 endpoints) = v3's "Data API" (36 endpoints)
106+
- v2's "Data API" (10 endpoints) = v3's "Meta API" (10 endpoints)
107+
108+
This is NOT just naming - you must load the opposite file for equivalent operations.
109+
110+
### 2. Base ID Now Required
111+
**100% of endpoints now require `baseId` in the path.**
112+
113+
```diff
114+
- /api/v2/tables/{tableId}/records
115+
+ /api/v3/data/{baseId}/{tableId}/records
116+
```
117+
118+
### 3. Pagination Redesigned
119+
**Complete breaking change in pagination.**
120+
121+
| v2 | v3 |
122+
|----|-----|
123+
| `offset=50&limit=25` | `page=3&pageSize=25` |
124+
125+
### 4. Sort Format Changed
126+
**String format replaced with JSON.**
127+
128+
```diff
129+
- sort=field1,-field2
130+
+ sort=[{"direction":"asc","field":"field1"},{"direction":"desc","field":"field2"}]
131+
```
132+
133+
### 5. Terminology Changes
134+
- `columns` → `fields`
135+
- `columnId` → `fieldId`
136+
- `ne` operator → `neq` operator
137+
138+
---
139+
140+
## 📊 Statistics
141+
142+
| Metric | v2 | v3 | Change |
143+
|--------|----|----|--------|
144+
| **Meta API Endpoints** | 137 | 10 | -93% |
145+
| **Data API Endpoints** | 10 | 36 | +260% |
146+
| **Total Endpoints** | 147 | 46 | -69% |
147+
| **Breaking Changes** | - | 147 | 100% |
148+
149+
---
150+
151+
## 🔍 Source OpenAPI Files
152+
153+
All analysis is based on these OpenAPI specification files:
154+
155+
- **v2 Meta API:** `docs/nocodb-openapi-meta.json` (137 endpoints)
156+
- **v2 Data API:** `docs/nocodb-openapi-data.json` (10 endpoints)
157+
- **v3 Meta API:** `docs/nocodb-openapi-meta-v3.json` (10 endpoints)
158+
- **v3 Data API:** `docs/nocodb-openapi-data-v3.json` (36 endpoints)
159+
160+
---
161+
162+
## 🛠️ Analysis Scripts
163+
164+
The following Python scripts were used to generate these reports:
165+
166+
1. **`analyze_api_diff.py`** - Basic endpoint comparison
167+
2. **`analyze_api_detailed.py`** - Comprehensive analysis with migration examples
168+
3. **`analyze_schemas.py`** - Query parameter and schema analysis
169+
170+
---
171+
172+
## ⏱️ Estimated Migration Timeline
173+
174+
| Phase | Duration |
175+
|-------|----------|
176+
| Analysis & Planning | 1-2 weeks |
177+
| Implementation | 2-3 weeks |
178+
| Testing | 2 weeks |
179+
| Deployment | 1 week |
180+
| **Total** | **6-8 weeks** |
181+
182+
---
183+
184+
## 🎯 Recommended Reading Order
185+
186+
### For Developers:
187+
1. [`API_V2_V3_MIGRATION_GUIDE.md`](./API_V2_V3_MIGRATION_GUIDE.md) - Start here
188+
2. [`NOCODB_API_SCHEMA_COMPARISON.md`](./NOCODB_API_SCHEMA_COMPARISON.md) - For parameter details
189+
3. [`NOCODB_API_V2_V3_COMPARISON.md`](./NOCODB_API_V2_V3_COMPARISON.md) - For complete reference
190+
191+
### For Architects:
192+
1. [`NOCODB_API_V2_V3_COMPARISON.md`](./NOCODB_API_V2_V3_COMPARISON.md) - Start here
193+
2. [`API_V2_V3_MIGRATION_GUIDE.md`](./API_V2_V3_MIGRATION_GUIDE.md) - For implementation strategy
194+
3. [`API_COMPARISON_V2_V3.md`](./API_COMPARISON_V2_V3.md) - For stakeholder presentation
195+
196+
### For QA/Testing:
197+
1. [`API_V2_V3_MIGRATION_GUIDE.md`](./API_V2_V3_MIGRATION_GUIDE.md) - Testing checklist section
198+
2. [`NOCODB_API_SCHEMA_COMPARISON.md`](./NOCODB_API_SCHEMA_COMPARISON.md) - Parameter validation
199+
200+
---
201+
202+
## 📝 Document Versions
203+
204+
All documents were generated on: **2025-10-10**
205+
206+
Based on OpenAPI specifications from the `docs/` directory.
207+
208+
---
209+
210+
## 🤝 Contributing
211+
212+
If you find discrepancies or need additional analysis:
213+
1. Check the source OpenAPI files first
214+
2. Run the analysis scripts to regenerate reports
215+
3. Submit findings with specific endpoint examples
216+
217+
---
218+
219+
## ⚖️ License
220+
221+
These documentation files are part of the NocoDB_SimpleClient project.
222+
223+
---
224+
225+
**Quick Links:**
226+
- [Migration Guide](./API_V2_V3_MIGRATION_GUIDE.md) | [Full Comparison](./NOCODB_API_V2_V3_COMPARISON.md) | [Schema Analysis](./NOCODB_API_SCHEMA_COMPARISON.md)

0 commit comments

Comments
 (0)