The Telligent Evolution platform 7.0 clearly identifies internal and public-facing APIs. The Platform API is exposed to extensions via a REST API, Widget and Email Extension API, Plugin API, and an in-Process API.
The Platform API (and only the Platform API) is guaranteed to work through upgrades and be documented through release notes. To ensure upgrade safety, Telligent strongly recommends using only the Platform API to implement customizations.
Using the Platform API
How do you ensure that you're using the Platform API? Follow these guidelines:
- If you're creating a Studio Widget or an email template, you only have access to the Platform API. There is nothing additional that you need to verify.
- If you're using the REST API, you only have access to the Platform API. There is nothing additional that you need to verify.
- If you're writing .net code that runs within the Telligent Evolution platform, ensure that you're only interacting with Telligent.Evolution.* assemblies via classes, enumerations, and interfaces that exist within the Telligent.Evolution.Extensibility.* namespace. The Platform API and plugin types exist solely in this namespace. Only this namespace is guaranteed to work through upgrades.
Following is a list of known issues where using the Platform API is not currently possible. Implementation guidelines are provided to minimize exposure to the internal API in these situations:
CSModules are deprecated in Telligent Evolution 7.0 and will be removed in Telligent Evolution 8.0. CSModules are completely replaced by plugins.
Setting the current user
This is a known limitation of the Platform API and one that will be addressed in a future release. Until it is addressed by the Platform API, techniques that worked in 5.6 and earlier releases of the platform can continue to be used. It is suggested to follow the guidelines on Using the internal API.
Retrieving current entities outside of widgets/email
Current entities (current blog, current group, etc) are currently only exposed to Studio Widgets and Email Templates via entity-specific Extensions. Until updates are made to the Platform API to support retrieving current entities within the context of web requests, follow the guidelines on Using the internal API.
Other platform functionality
See Using the internal API.
Using the internal API
To fully ensure upgrade safety, Telligent recommends using only the Platform API to implement extensions; however, the Platform API does not support all requested extensibility points, specifically: (1) custom applications, (2) custom non-content pages, (3) custom page URLs, and (4) items under Known issues above. In these situations, the internal API can still be used with the understanding that there is additional risk incurred on the extension:
- The internal API can change without notice.
- The internal API is not supported for development.
- Direct use of the internal API may bypass some security, event, and plugin-based functionality.
When accessing the internal API directly, Telligent recommends:
- Minimizing exposure. Only access the internal API when absolutely neccessary.
- Document exposure. Clearly document (for internal purposes at a minimum) the use of the internal API. When upgrading extensions for future versions of the platform, these areas will need to have special attention and may require additional work to upgrade and support changes in platform implementation and API exposure.