Menu

Search

The InstantKB REST API + API Explorer

Over the last few months we've been hard at work developing a completely new set of simple RESTful services for both InstantForum & InstantKB.

I'm pleased to share today some of our progress with this work by introducing the official release of our InstantKB 2016-1 BETA. We'll be sharing further news with regards to the forthcoming InstantForum 2016-3 BETA very soon. Stay tuned.

The InstantKB 2016-1 update adds over 50 new JSON based REST APIs and includes a lovely new visual API explorer within the administrator control panel helping you easily discover & test all the new services.

We are hoping these new HTTP based APIs will make it super easy for our customers or any developer to connect both InstantKB & InstantForum to any existing tools, systems or investments regardless of the language or platform being used.

Going forward we'll be developing our own officially supported 3rd party connectors & integrations for both InstantKB & InstantForum built upon the new REST APIs. We have some neat ideas around this I hope to share soon.

Try the API Explorer

Right now you can try the new API explorer within our InstantKB demo which has already been updated to our latest 2016-1 BETA release. If you would like to try the new API explorer please follow the steps below...

1. Visit the login page within our demo. Hit Login.
2. Once logged click here to visit the API Explorer.

Forthcoming JavaScript SDK

We are developing a promise based JavaScript SDK for the new REST APIs for both InstantKB & InstantForum. We expect the first release of this for InstantKB in the coming week or two and InstantForum shortly after.

The JavaScript SDK is a single .JS file you can include in your pages to very easily communicate with the new InstantKB or InstantForum REST API. You can see some code snippets below from this which show how to use the InstantKB JavaScript SDK to return tickets & articles or update a single ticket. Let's dig into the new REST API and exactly how this works...

How the new REST API Works

Want to create a simple browser extension or maybe a full blown cross platform Electron app in node that can connect to your InstantKB data? Of course you do :) As the new REST API is all HTTP based you can now call into your InstantKB database from any programming language on any platform. Oh the possibilities. So at a high level here are the basics for the new API...

Pluralized API End Points

All API endpoints that are pluralized (tickets, users, articles, tags etc) only support a single GET method and return JSON representing the data you requested.

The pluralized endpoints can be used to returned large result sets that often require client side paging. You can pass in a page index and page size within these calls and also further filter results by any criteria currently supported within the regular .NET API.

For example lets say you wanted to return all support tickets that have the keywords "lost password" using our JavaScript SDK. Your JavaScript code would look like this...

kb.tickets.getTickets({
page_index: 1,
page_size: 20,
args: {
keywords: "lost password",
sort_by: "TicketRank",
sort_order: "DESC"
}
}, function (tickets) {
for (var i = 0; i < tickets.length; i++) {
var val = $("<span>");
val.html(tickets[i].title + "<br/>");
$("#tickets").append(val);
}
});

We are working to keep the API very consistent. For example to return all articles that also contain the terms "lost password" you would use similar calls into our JavaScript SDK...

kb.articles.getArticles({
page_index: 1,
page_size: 20,
args: {
keywords: "lost password",
sort_by: "ArticleRank",
sort_order: "DESC"
}
}, function (articles) {
for (var i = 0; i < articles.length; i++) {
var val = $("<span>");
val.html(articles[i].title + "<br/>");
$("#tickets").append(val);
}
});

Singular API End Points

All API endpoints that are singular (ticket, user, article, tag etc) work with a single record within your InstantKB database and support all 4 HTTP verbs (GET, POST, PUT, DELETE). This allows you to select, insert, update or delete any record within your InstantKB database via the REST API.

For example using the new API if you wanted to return a JSON object representing a specific support ticket you could perform a GET request to api/ticket?id=123. Or maybe a specific article api/article?id=123 or maybe a user api/user?id=222

For a more complex example let's say you wanted to update the title of an existing ticket via the REST API using our JavaScript SDK this would look like so...

// get ticket with ID 123, change title & save again
kb.ticket.getTicket({ id: 123 }, function(ticket) {
if (ticket) {
ticket.title = "My New Ticket Title";
kb.ticket.updateTicket(ticket, function (updatedTicket) {
console.log("Updated Title: " + updatedTicket.title);
});
}
});

API Permissions & Security

By default the REST API will not be enabled within your InstantKB or InstantForum installation. As an administrator you will need to visit the administrator control panel for your installation and explicitly enable the REST API via the setting pages.

Application Key

When you enable the API this will generate a unique Application Key for your installation. This Application Key must be used for all public requests into your API. If only the Application Key is present within the request the request will be treated as an anonymous user meaning only public data will be returned. This is similar to you viewing your InstantKB installation within a web browser whilst not logged in or browsing your installation anonymously. The Application Key can be public and visible to all users within your application.

User Key

To return private user specific data or add, update or delete certain data you will need to combine a unique User Key with the Application Key within the authorization header for your request. This helps InstantKB identify the user who is making the request into the API and apply permissions accordingly. All API endpoints will only return the data you have permission to view depending on the User Key supplied within the authorization header.

For example if you connect to the API with a regular user account and attempt to request a ticket that does not belong to the user you are connecting as you will receive a 401 Unauthorized response. Similar if you try to POST, PUT or DELETE certain data depending on the user you are connected as and the data you are trying to modify you may receive a 401 Unauthorized response. Successful responses will always return a status code of 200 OK. If you connect to the API using an administrator user key you will have permission to update or delete all non required data. We will be detailing the specific end points and the required permissions for each end points and method within our forthcoming documentation.

If you connect to the API using a valid Application Key combined with a valid administrator or support agent User Key you will have permission to access or update any support ticket just like you would via the traditional agent control panel. If you connect to the API as a support agent you won't have permission to modify data that is only accessible tradionally via the InstantKB Admin CP. I.e. To update tabs, fields, workflows etc you must connect to the API with an administrator User Key.

You can reset API keys any time to revoke access either globally or on a per user basis. You can do this via the InstantKB Administrator control panel or also via the REST API. We expose 2 API endpoints (/auth and /login) that allow you to authenticate users (to return the user key) or generate new keys programmatically via the REST API.

For security purposes all user keys are guaranteed to be 100% unique for each user within your InstantKB database and are randomized between 160 to 250 characters in length with several layers of entropy. Unlike the Application Key, User keys should always be remain private and only ever visible to the user who the key belongs to. This is especially true for administrator or support agent user keys.

Application Secret

To help you manage keys programmatically via the API you also have a unique 160 to 255 character long Application Secret within your InstantKB installation.This is generated when you enable the API via the InstantKB Admin CP.

The Application Secret can be used in conjunction with the api/auth end point to reset the global Application Key or get the latest Application Key. The Application Secret never changes and should always remain private and never visible to end users. You would typically use the Application Secret only within server side code to ensure it's never visible to clients or end users of your application.

Documentation?

This is great but we know we need docs. It's still quite early in development however over the next few weeks we'll be introducing documentation covering the new REST API, authentication and the various end points and parameters within the API.

We'll be working on this documentation during the BETA and will have this ready around the time of the final release.

How To Help

We would love to work with existing InstantKB customers or developers to help us get the new REST API just right. If you would be interested in testing this out znc providing feedback of course please don't hesitate to contact us.

But wait, There's more

Alongside the new REST API for InstantKB 2016-1 we've now also moved all .aspx code-behind files over to C# - yay. Whilst the underlying source code for InstantKB has been written in C# or some time now we still had a number of .aspx.vb files for the various .aspx pages.

These VB files didn't contain any application code so took a bit of a back seat during the C# migration back in 2014. We've cleaned this up with 2016-1 and are now finally 100% C#. Adding C# to your InstantKB master page - luxury :)

Under the covers the server side .NET API has been completely refactoed with 2016-1 to align with the new REST API. For example all InsertUpdateX methods now return the new or updated object as opposed to the ID so this can be easily serialized into the JSON response from the WebAPI action methods.

And of course with 2016-1 we've also addressed several minor issues discovered since the initial 2016 release a last month.

That's It!

I'm super excited to share this new API and look forward to sharing further news as we get closer to the final InstantKB 2016-1 and InstantForum 2016-3 releases. As always we would love to hear from you. If we can answer any questions or assist please don't hesitate to post within our forums, pop a comment below or simply contact us.


Optionally provide your comments to help us improve this blog entry...

Thank you for your feedback!

Add Your Comments

Comments require login or registration.