Skip to content

Commit 58d9e59

Browse files
edmondasedmondas
committed
docs(api): add v2 endpoints, zone templates, groups, owners, remove internal API
1 parent 63c7d9d commit 58d9e59

1 file changed

Lines changed: 90 additions & 36 deletions

File tree

‎docs/configuration/api.md‎

Lines changed: 90 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -119,51 +119,98 @@ curl -u username:password \
119119

120120
## API Endpoints
121121

122-
### Zone Management
122+
Poweradmin provides two API versions. API v2 (introduced in v4.1.0) is recommended for all new integrations. API v1 remains available for backward compatibility.
123123

124-
- `GET /api/v1/zones` - List all zones
125-
- `GET /api/v1/zones/{id}` - Get zone details
126-
- `POST /api/v1/zones` - Create new zone
127-
- `PUT /api/v1/zones/{id}` - Update zone
128-
- `DELETE /api/v1/zones/{id}` - Delete zone
124+
### API v2 Endpoints *(v4.1.0+)*
129125

130-
### Record Management
126+
#### Zone Management
131127

132-
- `GET /api/v1/zones/{id}/records` - List zone records
133-
- `GET /api/v1/records/{id}` - Get record details
134-
- `POST /api/v1/zones/{id}/records` - Create record
135-
- `PUT /api/v1/records/{id}` - Update record
136-
- `DELETE /api/v1/records/{id}` - Delete record
128+
- `GET /api/v2/zones` - List all zones
129+
- `GET /api/v2/zones/{id}` - Get zone details
130+
- `POST /api/v2/zones` - Create new zone
131+
- `PUT /api/v2/zones/{id}` - Update zone
132+
- `DELETE /api/v2/zones/{id}` - Delete zone
137133

138-
### User Management
134+
#### Zone Owners *(v4.2.0+)*
139135

140-
- `GET /api/v1/users` - List users (admin only)
141-
- `GET /api/v1/users/{id}` - Get user details
142-
- `POST /api/v1/users` - Create user (admin only)
143-
- `PUT /api/v1/users/{id}` - Update user
144-
- `DELETE /api/v1/users/{id}` - Delete user (admin only)
136+
- `GET /api/v2/zones/{id}/owners` - List zone owners
137+
- `POST /api/v2/zones/{id}/owners` - Add zone owner (supports batch assignment via `user_ids` array)
138+
- `DELETE /api/v2/zones/{id}/owners/{user_id}` - Remove zone owner
145139

146-
### Permission Management
140+
#### Record Management
147141

148-
- `GET /api/v1/permissions` - List available permissions
149-
- `GET /api/v1/permissions/{id}` - Get permission details
142+
- `GET /api/v2/zones/{id}/records` - List zone records
143+
- `POST /api/v2/zones/{id}/records` - Create record
144+
- `PUT /api/v2/zones/{id}/records/{record_id}` - Update record
145+
- `DELETE /api/v2/zones/{id}/records/{record_id}` - Delete record
146+
- `POST /api/v2/zones/{id}/records/bulk` - Bulk create records
147+
148+
#### RRset Management
149+
150+
- `GET /api/v2/zones/{id}/rrsets` - List all RRsets in a zone
151+
- `GET /api/v2/zones/{id}/rrsets/{name}/{type}` - Get specific RRset
152+
153+
#### User Management
154+
155+
- `GET /api/v2/users` - List users
156+
- `GET /api/v2/users/{id}` - Get user details
157+
- `POST /api/v2/users` - Create user
158+
- `PUT /api/v2/users/{id}` - Update user
159+
- `DELETE /api/v2/users/{id}` - Delete user
160+
161+
#### Permission Management
162+
163+
- `GET /api/v2/permissions` - List available permissions
164+
- `GET /api/v2/permissions/{id}` - Get permission details
150165

151-
### Permission Templates
166+
#### Permission Templates
152167

153-
- `GET /api/v1/permission-templates` - List permission templates
154-
- `GET /api/v1/permission-templates/{id}` - Get permission template details
155-
- `POST /api/v1/permission-templates` - Create permission template
156-
- `PUT /api/v1/permission-templates/{id}` - Update permission template
157-
- `DELETE /api/v1/permission-templates/{id}` - Delete permission template
168+
- `GET /api/v2/permission-templates` - List permission templates
169+
- `GET /api/v2/permission-templates/{id}` - Get permission template details
170+
- `POST /api/v2/permission-templates` - Create permission template
171+
- `PUT /api/v2/permission-templates/{id}` - Update permission template
172+
- `DELETE /api/v2/permission-templates/{id}` - Delete permission template
158173

159-
### Internal API Endpoints
174+
#### Zone Templates *(v4.2.0+)*
160175

161-
The following endpoints are available for internal use (session-based authentication):
176+
- `GET /api/v2/zone-templates` - List zone templates
177+
- `GET /api/v2/zone-templates/{id}` - Get zone template details
178+
- `POST /api/v2/zone-templates` - Create zone template
179+
- `PUT /api/v2/zone-templates/{id}` - Update zone template
180+
- `DELETE /api/v2/zone-templates/{id}` - Delete zone template
181+
- `GET /api/v2/zone-templates/{id}/records` - List template records
182+
- `POST /api/v2/zone-templates/{id}/records` - Add template record
183+
- `PUT /api/v2/zone-templates/{template_id}/records/{id}` - Update template record
184+
- `DELETE /api/v2/zone-templates/{template_id}/records/{id}` - Delete template record
162185

163-
- `GET /api/internal/zones/{id}/validate` - Validate zone configuration
164-
- `GET /api/internal/users/{id}/preferences` - Get user preferences
165-
- `PUT /api/internal/users/{id}/preferences` - Update user preferences
166-
- `POST /api/internal/validation` - Validate various data types
186+
#### Group Management *(v4.2.0+)*
187+
188+
- `GET /api/v2/groups` - List groups
189+
- `GET /api/v2/groups/{id}` - Get group details
190+
- `POST /api/v2/groups` - Create group
191+
- `PUT /api/v2/groups/{id}` - Update group
192+
- `DELETE /api/v2/groups/{id}` - Delete group
193+
- `GET /api/v2/groups/{id}/members` - List group members
194+
- `POST /api/v2/groups/{id}/members` - Add member to group
195+
- `DELETE /api/v2/groups/{id}/members/{user_id}` - Remove member from group
196+
- `GET /api/v2/groups/{id}/zones` - List group zones
197+
- `POST /api/v2/groups/{id}/zones` - Assign zone to group
198+
- `DELETE /api/v2/groups/{id}/zones/{zone_id}` - Remove zone from group
199+
200+
### API v1 Endpoints (Legacy)
201+
202+
API v1 is available for backward compatibility. Consider migrating to v2 for new integrations.
203+
204+
- `GET/POST /api/v1/zones` - List / create zones
205+
- `GET/PUT/DELETE /api/v1/zones/{id}` - Get / update / delete zone
206+
- `GET/POST /api/v1/zones/{id}/records` - List / create records
207+
- `PUT/DELETE /api/v1/zones/{id}/records/{record_id}` - Update / delete record
208+
- `GET/POST /api/v1/users` - List / create users
209+
- `GET/PUT/DELETE /api/v1/users/{id}` - Get / update / delete user
210+
- `GET/POST /api/v1/permission-templates` - List / create templates
211+
- `GET/PUT/DELETE /api/v1/permission-templates/{id}` - Get / update / delete template
212+
- `GET /api/v1/permissions` - List permissions
213+
- `GET /api/v1/permissions/{id}` - Get permission details
167214

168215
## API Documentation
169216

@@ -186,8 +233,7 @@ When `docs_enabled` is true, interactive API documentation is available at `/api
186233
],
187234
```
188235

189-
!!! tip
190-
To enable audit logging for API operations, use the [audit logging settings](logging.md) (`logging.database_enabled` and `logging.syslog_enabled`) instead.
236+
> **Tip:** To enable audit logging for API operations, use the [audit logging settings](logging.md) (`logging.database_enabled` and `logging.syslog_enabled`) instead.
191237
192238
### Security Best Practices
193239

@@ -337,8 +383,16 @@ GET /api/v1/users?page=2&limit=25
337383

338384
## Version History
339385

386+
### v4.2.0
387+
- **Added:** Zone template CRUD endpoints (API v2)
388+
- **Added:** Zone owners endpoints with batch assignment (API v2)
389+
- **Added:** Group management endpoints - members and zones (API v2)
390+
- **Added:** RRset endpoints (API v2)
391+
- **Added:** Bulk record creation endpoint (API v2)
392+
340393
### v4.1.0
341-
- Improved API stability and error handling
394+
- **Added:** API v2 with consistent response wrapping
395+
- **Added:** Permission validation for API endpoints
342396

343397
### v4.0.4
344398
- **Fixed:** Basic Auth TypeError when LDAP authentication is enabled (issue #799)

0 commit comments

Comments
 (0)