API Overview


  7 months ago by Admin

Please note that we have a separate API which allows you to forward traffic from your server to ours (see: Using a custom domain with Taveo). This document refers to our full featured, developer focused API.


This document gives a detailed overview of the Taveo Server Application Programming Interface

This document describes version 1.0 . Currently, the base URL for all API requests is:

https://api.taveo.net/1/<method>



Basic definitions and API usage
  1. All requests shall be made over SSL (aka HTTPS). Requests to HTTP will be 301 redirected to HTTPS.

  2. All requests shall use the GET method.

  3. All parameters passed to API requests should use standard HTTP Query String notation.

  4. The API will use HTTP status codes (404, 500, 401, 429, etc) to indicate errors. The exact definition of these can be found below.

  5. The API response will be of the type JSON or JSONP, depending on the value of the callback parameter. Error responses adhere to this as well.

  6. All requests shall include an apikey parameter. Requests without this parameter will return a 401 Unauthorized error


A simple example

In this example we are accessing the /create method to create a new link. This API endpoint includes other options not shown here, see the full /create documentation for a complete list of required and optional parameters.

Request:
https://api.taveo.net/1/create?apikey=0F0F0F0F0F0F0F0F0F0F0&destination=http%3A%2F%2Fwww.google.com%2Fnews
Response:
{
"status": "ok",
"msg": "Successfully Created Link",
"url": "http://tav.so/r3j2B"
}


API HTTP Response Codes

The API can respond in two ways. If your request was valid, you will receive a HTTP 200 OK. If there was an issue, you will receive one of the following 4XX/5XX HTTP Responses.

HTTP Status Code Code Meaning Recommended Action
200 OK

Your request was processed correctly. check JSON(P) response data for more information.

Nothing.

401 Unauthorized

You are not currently authorized to access this resource

Bad or missing apikey parameter. Check apikey you are passing with this request

404 Not Found

API resource not found.

Check the URL you are requesting, specifically the method https://api.taveo.net/1/<method>

429 Too Many Requests

You are accessing the API at too fast of a rate OR you have made 10+ requests in the past 30 minutes which generated errors

Set your watch,clock,timer,etc for 30 minutes in the future and try again then. Contact Support if you continue to have problems of this type.

500 Internal Server Error

Congrats, you have found a bug in the API server!

A log of this request was made, but please e-mail Support and let us know what you did to generate this message.



API Responses

Although the API can return JSON or JSONP formatted data, the actual content of the message will not change. JSONP simply wraps the returned data inside a JavaScript function. Therefore, all references you see to response formats, object names, etc. are exactly the same between both response types.

All API responses will contain a status parameter!

This parameter is important and should be the first element checked when parsing an API response

  1. The status parameter shall be used to indicate the result of the API request.

  2. Currently, the possible values of the status parameter are: "ok" and "error" (We may add additional error-like indicators in the future)

  3. If the status parameter is equal to "error" no guarantees are made about any other parameter (except for msg, see below), they may be missing, garbled or incorrect. If you receive an API response with a status of error, immediately stop processing this response.

  4. If the status parameter is equal to "error" a msg parameter will be included with the response.

  5. The msg parameter will have a human readable string as it's value. This message will provide a clue or context to the reason the API request was unsuccessful.

  6. Responses with a status of "ok" may have a msg parameter, but that is not guaranteed. In general, it is recommend to ignore the msg parameter when status == "ok" .



API Request methods

The following is a list of available API methods, clicking the link will take you to article that explains that method in more detail

Method Description
create Used to create a new Link. Has required and optional parameters. Returns Taveo Link URL
overview Used to retrieve general Account information. Takes no extra parameters. Returns Taveo Account info. Can be used to test API Key.
links.bydest Used to retrieve Taveo Links for a given destination URL. Has required parameters. Returns array containing 0 or more Links.
links.all Used to retrieve all of your Taveo Links. Takes no extra parameters. Returns array containing 0 or more Links.











Can't find the answer to your question? Contact our support team