Getting started with ThirdPresence API
From ThirdPresence Wiki
Contents |
The API is a REST-based API for accessing the content and metadata in your account. Because it is a REST-based API, it can be accessed from a wider variety of places in your web applications, not just on the client, but for example in your dynamically generated web pages or server-side synchronization processes.
To prevent unauthorized access to the metadata in your account, access to the API is protected with tokens that you pass as a parameter when making API calls. Like other web-based APIs, tokens are generated for you by and protected by you.
Then, after you read this introduction, check out the other documentation about the API:
ThirdPresence API method reference guide
ThirdPrsence API object reference guide
REST and JSON
REST (Representational State Transfer), is a standard way of accessing data using HTTP GET requests. It is a somewhat simplified version of SOAP. It effectively abstracts the implementation details of the working system (ThirdPresence) and its state. All your code needs to understand is the format of the requests and data that is sent back.
The API includes read methods and write methods.
The API consists of a set of methods to perform a variety of queries on ThirdPresence and the methods return sets of data in DTOs or Data Transfer Objects.
For example, one API method is getVideos, which returns a list of VideoItems, where each VideoItem contains the metadata for a specific video.
Return data is formatted as JSON string. JSON (JavaScript Object Notation) is a lightweight way of transferring data in a text-based, human-readable format for representing simple data structures and associative arrays (called objects).
With the Write API methods, you can create a client application that integrates your account e.g. with your content management system. Write API provides the methods to publish to ThirdPresence new video files and add related metadata to them.
API basics
Method calls are basically HTTP GET requests to a particular URL on servers. The request includes the name of the method and the arguments, which are passed as parameters in the URL. The body of the HTTP response contains the results of the HTTP call as a JSON string. All API calls use the base URL http: //api.thirdpresence.com/[api-version]/[service]/. Accessing Services through IP addresses is not supported and should be avoided at all times.
Method calls require an authentication token. Tokens are issued to accounts by ThirdPresence and the token gives you access to your account using the API. There are separate tokens for read methods and write methods in the API. You append your token to the call as a URL parameter, authToken=<tokenString>, where tokenString is your URL-encoded token.
For example, to retrieve all videos in your account, HTTP request would look like:
http://api.thirdpresence.com/10-09/video/?Action=getVideos&authToken=sdai3104aasscdtgewAAxs098123po232llln
Use the API from your platform or application
Because API requests are simple HTTP calls, you can include them just about anywhere in your (web) application. Every popular language includes support for making HTTP requests. In addition, we are in the process of creating SDKs that you can include in your applications as native classes for easy API access.
The points that you need to consider when integrating ThirdPresence to your system are:
- In case you are accessing ThirdPresence from your web application, it is usually beneficial to use AJAX or Comet development techniques to ensure that the system is responsive when the call is being handled on the background
- When receiving the response, you need to parse the JSON string into native objects so that you can work with the data. JSON does not specify any particular data order so your parsing code would need to be generic enough to ensure that it does not fail if the fields are received in various orders.
Error handling
The API returns errors as JSON strings with an error parameter in following way:
{"errorresponse": "true", "message": "Content could not be created.","code":401}
Your code should always try and handle errors. By handling the errorresponce parameter of the result object (after parsing the JSON respone), the user is of what might have gone wrong and how the error can be fixed.
Error messages returned by the API include a numerical error code that classifies errors by type. For more information, see the Error Message Reference and list of Error codes.
Token management
Have extra precautions to keep your tokens secure — the tokens provide direct access to your content on ThirdPresence.
This is especially important if you're considering client-side API calls, i.e. directly copy-pasting the token to your JavaScript code. Any of your web visitors can use "view source" and see your API token, which they could then use to modify your video assets and upload malicious content.
In case you don't have a token for your account, please send email to support@thirdpresence.com for requesting it and we'll send it to you!