Document undocumented endpoints

Based on what I am seeing in the connectapi source code and docs, there appear to be Posit Connect API endpoints available that are not documented on Posit Connect API Reference. For example, I do not see any documentation on that page about editing Variant settings, or updating Schedules.

Can the docs be updated to include all available endpoints?

Howdy! Thanks for reporting this!

We are in the process of refactoring many of the non-public APIs into stable v1 endpoints. Unfortunately we do not have an ETA for when these APIs will land. However, we are reluctant to document and standardize these other / undocumented API endpoints since it would potentially give false impressions around our attachment to these APIs.

Currently, these undocumented APIs are considered "experimental," and we expect them to change across Connect releases. The reason we have included them in the connectapi package is that we can

  • warn about the status of the API when used
  • try to maintain backwards compatibility in the client library (i.e. release a new version of connectapi that switch to the new APIs w/ minimal customer impact)
  • when backwards compatibility is not possible, we can warn about changes across connectapi releases

If you are interested in seeing the current state of affairs, you can use this article on our pkgdown site:

Our goal is definitely to remove these weird undocumented endpoints. However, the current plan is to be mostly by replacing with new APIs rather than formalizing APIs with known faults :sweat_smile:

What primarily draws you to the need for documentation? Are you using another language or scripting mechanism for calling Connect APIs?

1 Like

Sorry for the late reply! Thank you for clarifying the work that's in progress.

As for your question: We are making extensive use of both the public v1 API and also connectapi in scripts that help us manage our content on Connect (we have a lot of content!). As I was getting familiar with both the public v1 API and connectapi, it was unclear to me as an end user what the relationship was between the two. For example: if connectapi is a wrapper around the public API, why do I see some functionality in connectapi that is not in the public API? Where the functionality does overlap, am I guaranteed equivalent behavior from both (so which to use is a matter of personal preference)? I looked for documentation and went through a lot of trial-and-error to help me answer these questions, but overall encountered a lot of friction.

Two breakthroughs really helped me:

  1. Figuring out how to use the R6 classes on connectapi. Once I started leveraging these, I could see the direct correlation between these and the public API. The slim documentation of these classes was a large barrier to entry for me, but now that I understand it, they've been a very powerful asset. It's interesting that connectapi both has direct 1:1 wrappers around the public API, but also additional wrapper functions around those. I think that delineation could be more clear. For example, for the longest time I was using connectapi::deploy_current() to re-render my content. It's overkill because it both restores and renders, but it's all I could find. Eventually I bumped into Variant$render(), and now I'm cooking with gas. :fire:

  2. A recent meeting with Posit which made the differences and relationship between the public v1 API and `connectapi a lot clearer to me. My takeaways were:

  • The public v1 API is the stable place where Connect APIs are made available. It makes a lot of guarantees of stability to the end user.
  • connectapi is a wrapper for these public APIs, and also has served as a platform for exposing Connect APIs that have not yet been made stable and released in the public v1 API. This gives the user access to more capabilities, but is experimental and subject to breaking changes.

Both of those things have unblocked me, so I no longer have an acute need, however I imagine other users following behind me will likely have similar questions and confusions!

Thanks again!

1 Like