API v2

Motivation

• We need good REST API for Voedger

• Old API must still be available until the new one is fully developed, so we can continue with AIR

Functional design

API Conventions

• API URL

• HTTP methods and processors

• Naming conventions

• Query constraints

• Error handling

REST API Paths

Action	REST API Path
Authentication
Creates a new principal token	POST /api/v2/apps/{owner}/{app}/auth/login
Refreshes a valid principal token	POST /api/v2/apps/{owner}/{app}/auth/refresh
Logins
Create(register) a new user	POST /api/v2/apps/{owner}/{app}/users
Change user password	POST /api/v2/apps/{owner}/{app}/users/change-password
Devices
Create(register) a new device	POST /api/v2/apps/{owner}/{app}/devices
Docs and records
Create document or record	POST /api/v2/apps/{owner}/{app}/workspaces/{wsid}/docs/{pkg}.{table}
Update document or record	PATCH /api/v2/apps/{owner}/{app}/workspaces/{wsid}/docs/{pkg}.{table}/{id}
Deactivate document or record	DELETE /api/v2/apps/{owner}/{app}/workspaces/{wsid}/docs/{pkg}.{table}/{id}
Read document or record	GET /api/v2/apps/{owner}/{app}/workspaces/{wsid}/docs/{pkg}.{table}/{id}
Read from CDoc Collection	GET /api/v2/apps/{owner}/{app}/workspaces/{wsid}/cdocs/{pkg}.{table}
BLOBs
Create BLOB	POST /api/v2/apps/{owner}/{app}/workspaces/{wsid}/docs/{pkg}.{table}/blobs/{fieldName}
Read BLOB	GET /api/v2/apps/{owner}/{app}/workspaces/{wsid}/docs/{pkg}.{table}/{id}/blobs/{fieldName}
Temporary BLOBs
Create temporary BLOB	POST /api/v2/apps/{owner}/{app}/workspaces/{wsid}/tblobs
Read temporary BLOB	GET /api/v2/apps/{owner}/{app}/workspaces/{wsid}/tblobs/{suuid}
Extensions
Execute Command	POST /api/v2/apps/{owner}/{app}/workspaces/{wsid}/commands/{pkg}.{command}
Read from Query	GET /api/v2/apps/{owner}/{app}/workspaces/{wsid}/queries/{pkg}.{query}
Views
Read from View	GET /api/v2/apps/{owner}/{app}/workspaces/{wsid}/views/{pkg}.{view}
Notifications
Create channel, subscribe and start watching	POST /api/v2/apps/{owner}/{app}/notifications
Subscribe to an extra view	PUT /api/v2/apps/{owner}/{app}/notifications/{channelId}/workspaces/{wsid}/subscriptions/{pkg}.{view}
Unsubscribe from subscription	DELETE /api/v2/apps/{owner}/{app}/notifications/{channelId}/workspaces/{wsid}/subscriptions/{pkg}.{view}
Schemas
List app workspaces	GET /api/v2/apps/{owner}/{app}/schemas
List workspace roles	GET /api/v2/apps/{owner}/{app}/schemas/{pkg}.{workspace}/roles
Read workspace role schema	GET /api/v2/apps/{owner}/{app}/schemas/{pkg}.{workspace}/roles/{pkg}.{role}

Limitations

• The following functions should not be calle directly:

  • c.sys.CUD

  • q.sys.Collection

Addressed issues

• API Gateway (APIv2) #1162

See Also

• Query Processor

• API Gateway Implementation