Use v1 APIs

[nealrichardson]

posit-dev/rsconnect-python#731 and rstudio/rsconnect#1280 can be references. The new APIs are mostly drop-in replacements but there are a couple of naming differences.

[nealrichardson]

Implementation Plan: Migrate to v1 APIs

Summary

Migrate rsconnect-ts from using undocumented/legacy application endpoints to the stable v1 content APIs. The v1 APIs are mostly drop-in replacements but use "content" terminology instead of "application" and consistently use GUIDs instead of numeric IDs.

Decision: Keep existing method names (createApp, getApp, etc.) for backwards compatibility.

API Endpoint Changes

Operation	Current (Legacy)	New (v1)
Create content	POST applications	POST v1/content
Get content	GET applications/${id}	GET v1/content/${guid}
Update content	POST applications/${id}	PATCH v1/content/${guid}
List content	GET applications	GET v1/content
Upload bundle	POST applications/${id}/upload	POST v1/content/${guid}/bundles
Deploy	POST applications/${id}/deploy	POST v1/content/${guid}/deploy
Get bundle	GET bundles/${id}	GET v1/content/${guid}/bundles/${id}

Implementation Details

1. APIClient.ts Changes

createApp()

// Before: POST applications { name: appName }
// After:  POST v1/content { name: appName }

getApp()

// Before: GET applications/${appID}  // accepts number|string
// After:  GET v1/content/${guid}     // string GUID only

• Change parameter type from number|string to string

updateApp()

// Before: POST applications/${appID}
// After:  PATCH v1/content/${guid}

• HTTP method changes from POST to PATCH
• Change parameter type from number|string to string

listApplications()

// Before: GET applications?count=X&start=Y&cont=Z&filter[]=name:foo
// After:  GET v1/content?page_size=X&page_number=Y&name=foo

• Pagination params: count → page_size, start → page_number, no cont (cursor-based)
• Filter syntax: filter[]=name:foo → name=foo (direct query param)
• Response: { applications: [], total, count, continuation } → array with Total-Count header

Internal usage:

• Deployer.findExistingAppByName() uses filter: [\name:${name}`]` - needs update
• ListApplicationsPager uses pagination params - needs update

uploadApp()

// Before: POST applications/${appID}/upload (appID: number)
// After:  POST v1/content/${guid}/bundles (guid: string)

• Change parameter from appID: number to guid: string

deployApp()

// Before: POST applications/${appID}/deploy { bundle: bundleID }
// After:  POST v1/content/${guid}/deploy { bundle_id: bundleID }

• Change parameter from appID: number to guid: string
• Request body field: bundle → bundle_id
• Response changes from ClientTaskV0Response to ClientTaskV1Response

getBundle()

// Before: GET bundles/${bundleId}
// After:  GET v1/content/${guid}/bundles/${bundleId}

• Add contentGuid: string as first parameter
• Signature: getBundle(bundleId) → getBundle(contentGuid, bundleId)

2. Deployer.ts Changes

In deployBundle():

• Line 90: getBundle(app.bundleId) → getBundle(app.guid, app.bundleId)
• Line 193: updateApp(app.id, ...) → updateApp(app.guid, ...)
• Line 202: uploadApp(app.id, bundle) → uploadApp(app.guid, bundle)
• Line 210: deployApp(app.id, ...) → deployApp(app.guid, ...)

In findOrCreateByName():

• Line 248: getApp(name) - already works (receives GUID)

In findExistingAppByName():

• Line 280: Change from listApplications({ count: 1, filter: [\name:${name}`] })tolistApplications({ pageSize: 1, name: name })`

3. ListApplicationsPager.ts Changes

• Adjust for v1 cursor-based pagination
• v1 returns array directly (not wrapped in { applications: [] })
• Update pagination params handling

4. api-types.ts Changes

• Update ListApplicationsParams for v1 pagination
• Update ListApplicationsResponse for v1 format
• Remove ClientTaskV0Response import from Deployer (use v1)

Files to Modify

1. src/APIClient.ts - Update endpoints to v1, change ID params to GUIDs
2. src/api-types.ts - Update pagination types
3. src/Deployer.ts - Pass GUIDs instead of numeric IDs
4. src/ListApplicationsPager.ts - Update pagination logic

Implementation Order

1. api-types.ts - Update types first
2. APIClient.ts - Update all endpoints to v1
3. Deployer.ts - Update method calls to pass GUIDs
4. ListApplicationsPager.ts - Update pagination logic

Verification

1. npm run build - Verify TypeScript compilation
2. npm test - Run all tests
3. Manual integration test against real Connect instance (if available)

Notes

• v1 APIs have been available for years, no server version checks needed
• Some endpoints already use v1 (tasks, environment, vanity URLs)
• Dashboard URL included in v1 responses

External usage (rstudio/actions):

• Uses: APIClient.serverSettings(), Deployer.deployManifest(), EnvironmentUpdater.updateAppEnvironment(), ClientTaskPoller.poll(), ApplicationPather.strictAppPath()
• Does NOT use: listApplications() or ListApplicationsPager
• This means the listApplications changes are low-risk since no external callers use filter params

---

Pre-requisite: Add integration tests for the external usage functions before refactoring.