It's no secret that for some time Telligent Community has had a REST API, and that if you were a developer wanting to interact with your community from a third party application this was how it was done. This hasn't changed, the APIs simply have gotten more robust as more functionality is introduced and exposed.
Lets be honest though, depending on what you want to do, REST isn't always easy and straight forward. It's one thing if you want to make a simple call to list a few blog posts, however more fully functional integration requires more of an investment.
First, there is communication. You need to write the code to set up a request, code to transmit that request, and then code to handle the response. Remember this is REST so the response is just data in XML or JSON format so you are going to need to interpret that data in a usable way. This means more code to parse or deserialize that data.
Second there is authentication. Always want to make your REST calls as a single user? Easy. Want to vary the calls by user context...significantly more complicated. This means code to identify your system's authenticated user, then more code that makes sure there is a corresponding user in the community. Once that is done you need to modify your communication code to include the appropriate headers.
Last, lets not forget that once all this is done, you still need to build a meaningful UI to makes use of all this.
Now this all sounds daunting, and I want to make sure I am clear that as complex as this is, it's not a Telligent Community issue, it's a common complication of a REST based infrastructure. I am also sure you have already decided how to tackle this problem, after all there is a lot of repeatable code. That's right, you are going to build your own framework. Then once that framework is done it's a simple matter of invoking it when it's needed. This is of course the most efficient way to tackle the problem and we couldn't agree more....we just decided we would help. The Telligent Community REST SDK was built for you to use in place of building a complex framework, and by the way...its 100% open source.
Now the disclaimers.... this is a .NET SDK. If you are not working on a .NET based Application(specifically .NET 4.5+), this isn't going to work out...its not personal. Also this SDK currently targets server side interactions, so javascript developers its not going to "just work". We have plans to add more client side functionality, but for now you will still require a server side proxy for client based calls. This is something for another topic.
What the SDK Does
The SDK is a framework, that thing you were thinking about building yourself as I explained the complexities of REST infrastructures. Its designed to make interacting with a Telligent Community's REST APIs easy. How does it this? ...so glad you asked.
Simplified Authentication
You can use a single user or use APIs to tell the SDK who is logged on to your system. You can even just let Telligent Community be your user repository. The SDK uses OAuth to authenticate with your community so it will automatically obtain user specific authentication tokens. It can present the Oauth login screen or if you are managing users and authentication in your application just add a simple API call that tells the SDK who should be logged in and it will automatically create the user in your community and set the appropriate token in subsequent requests.
REST Calls Without the Overhead
Depending on the endpoint, you can make a fully authenticated call to REST in as little as 2 lines of code. All you need to know is the url of the REST endpoint and what data is needed to successfully make your call. The SDK uses the concept of a host object that you create when your application starts to manage REST interactions . You then simply get a reference to that host and make the call using one of the GET/PUT/POST/DELETE methods.
Deserialize Responses Only if you want to
The SDK gives you several options when it comes to dealing with REST response data. You can get data back in the following formats:
- XElement (XML requests only)
- String
- Stream
- dynamic
The most powerful of these is Dynamic. In simple terms dynamics are just objects that are not evaluated when compiled but rather at runtime. You can interact with a dynamic like a concrete object that has its own methods and properties without actually having to create a concrete class.
Take this JSON response:
{"FirstName":"John","LastName":"Doe"}Most developers will parse this somehow or deserialize it into a proprietary concrete class. This means an object you need to update to expose more functionality from the response. The SDK can turn this into a dynamic type making this unnecessary. Instead you can just interact with its properties directly like it was a concrete class:
Code abbreviated for informational purposes
dynamic response = Host.GetToDynamic(...); //Host API call
var firstname = response.FirstName;
var lastname =response.LastName;
Async Ready
The SDK supports task-based asynchronous calls along side standard synchronous ones so you can choose to implement async patterns when you feel its appropriate for your application.
Compatibility
We recommend Telligent Community 8.5 or later, though earlier versions may work. The goal is that the SDK lives independently of the core community software so while you may upgrade, you don't need to upgrade the SDK. The reverse is also true, you should be able to upgrade the SDK without updating your community. While the SDK may introduce features specific to a new version of Telligent Community, our goal is that if you try to use them against an incompatible version they would fail gracefully.
I'm Sold, Where Do I Get It?
There are 2 ways to get it. The full source is available on GitHub. This is also where the documentation and issue tracking will be. We also encourage folks to contribute!
If you just want the latest stable release, you can install it directly in Visual Studio using NuGet, just look for Telligent Community Server REST SDK.
You also may be itching for more information on how to use it. The wiki in GitHub should get you started and you can start asking questions in our Developer Forums today! Additionally within the next 1-2 weeks I will publishing an educational topic that starts to get into the actual implementation of an SDK based solution. Be sure to subscribe to this post and blog and I will give an update once this is available.