TeamHub REST API

Overview of TeamHub REST API

Design Principles

The design of TeamHub's REST API follows several guiding principles:

  • All request URIs must use the /services/v2/ prefix.
  • Operations requests to related, contained, or child nodes must also contain a prefix with the URI of the parent container node in order to successfully receive a response from the REST API.
  • For operations that use the GET HTTP method, the accept HTTP header specifies an ordered list of MIME types that are acceptable by the client.
  • URI/URL segments that identify the type of entity involved use the uncapitalized, plural name of that entity.

Allowed HTTP Requests

There are 4 types of HTTP requests that can be used with the TeamHub REST API.

  • GET requests are made to retrieve information (badge information, analytics, etc) from the TeamHub platform.
  • POST requests create new instances of entities (topics, questions, etc.) on the TeamHub platform.
  • PUT requests update or extend the state of existing entities (up-voting, down-voting, etc) on the TeamHub platform.
  • DELETE requests remove instances of entities (remove topic, remove answer, etc) from the TeamHub platform.

Note: The HTTP method of a request can be overridden with request parameter ?_method=METHOD

MIME types

API warning:

  • The API requests covered in this guide were tested in TeamHub version 1.6.5 If you are using an earlier version, some of the requests may not function as described in this guide.
  • When using the TeamHub REST API, please keep in mind that it is currently under active development, and is likely to change as that development occurs. Requests may be modified or removed. If you ever notice that this REST API guide is out of date, please contact our Tech Docs team to make updates (In your email, please include specifics about what needs to be updated).
  • Not all of our partners have access to the REST API by default. If you are unsure of your access, or if you simply need help taking advantage of this functionality, please reach out to your dedicated Customer Success Representative or visit the Success site.

Note on MIME types:

  • All of the examples in this guide use the JSON MIME type and are written as cURL commands.

Following the standard approach to designing REST web-services, the HTTP accept header specifies an ordered list of MIME types that are acceptable by the client. The implementation of the server supports the following MIME types:

  • application/json for JSON content
  • application/xml for XML content

Optionally, the following MIME types may also be supported:

  • (X)HTML text/html
  • application/xhtml+xml

The actual MIME type sent by the server in response to an API request is specified within the HTTP response content-type header.

In addition to the headers, resource and file extensions can also be used to specify MIME types (.json for JSON content, or .xml for XML content).

Requirements

Before you are able to make API requests with TeamHub, you must first Enable the REST API in TeamHub and Grant the Use API permission to a TeamHub User.

Overview of TeamHub REST API