Web Masters - Implementing the RelayAPI for Web Tools

RelayAPI is a web service that serves content from WebTools, via HTTPS, so that developers can easily integrate this content into a custom dynamic site.

How the RelayAPI Works

RelayAPI creates a handshake between the WebTools engine and your dynamic website. Content is stored in your account on the WebTools system and is automatically called and displayed on your website when the appropriate page is loaded by a browser. The content appears on your site and is associated with your URL.

Getting Started

You will retrieve your content through a series of HTTPS requests to your custom RelayAPI URL. The server requires a two part authentication to access the data. The first part is your WebTools Domain. The second part is an API Key. Do not share this information it is specific for your account!

The URL for your account is in the form:

"https://relayapi.autonettv.com/antv/v1/[webtools_domain]/[api_key]//[type of data]/?parameters"

The [webtools_domain] part of the URL is the first part of the authentication system, and is assigned you by the WebTools system.

The [api_key] part of the URL is the second part of the authentication system, and is generated automatically by the WebTools system.

It is important not to share your API key or post it where it can be found; the WebTools Domain and API key are the only level of security to prevent other people from connecting to your account and obtaining your content. Your API key is not your account password. If someone learns your API key, they will not be able to access your WebTools account.

RelayAPI is designed to be simple. You simply use this URL to send a request to WebTools, and the RelayAPI will return the requested data as a JSON array. You will open this URL using your programming language of choice and read its contents. For example, if you were using PHP, you would use the 'file_get_contents' function to get the contents of the URL.

In PHP the request will look something like this:
$result = json_decode( file_get_contents("https://relayapi.autonettv.com/antv/v1/[webtools_domain]/[api_key]/[type of data]/?parameters") );

You can request three types of data: Posts, Archives, and Categories.

Retrieving Posts

Posts are your content, and contain a unique ID, a title, a post date, and custom content. You can edit your RelayAPI content in the 'Articles' section of your site.

In PHP a request for post will look like this:
$result = json_decode( file_get_contents("https://relayapi.autonettv.com/antv/v1/[webtools_domain]/

/[api_key]/posts/?parameters") );

Parameters are optional. If no parameters are specified RelayAPI will return your most recent 10 posts.

There are 6 parameters for retrieving posts:

Name	Description	Default
post_id	The unique ID of the Post that you want to retrieve. If this parameter is set, it will override all other parameters. This parameter must be an integer value.	Not Set
limit	The number of results to return. This parameter must be an integer.	10
start_date	The start date and time for post. When set, RelayAPI will return only post with a post date after the start_date. This parameter may be a timestamp or any well formatted date string (i.e. "[numeric datetime]" or "[string datetime]")	Not Set
end_date	The end date for post. When set, RelayAPI will return only post with a post date before the end_date. This parameter may be a timestamp or any well formatted date string (i.e. "[numeric datetime]" or "[string datetime]")	The current date and time
offset	Offset the results by this amount. This parameter must be a positive integer.	0
search	A search parameter for the post. When set, RelayAPI will return only post that fit the search parameter (both title and content are searched).	Not Set
category_id	The unique ID of the Category that you want to retrieve. This is used to narrow results.	Not Set

Understanding the results of a post query

The result of the above request will fill the $result variable with an array of objects. Each object will have the following variables:

Name	Description	Type
post_id	The unique ID of the Post.	unique integer value.
post_date	The date this Post was published.	Timestamp 2000-01-01 00:00:00
title	The title of the Post.	String
content	The content of the Post	String
category	The CategoryID of the post. If this post is "uncategorized", then this field will not exist.	Integer

Some Examples

Here are some examples of queries for different scenarios.

Retrieve the most recent 10 posts in PHP:
$result = json_decode( file_get_contents("https://relayapi.autonettv.com/antv/v1/[webtools_domain]/

[api_key]/posts/") );

Retrieve the most recent 5 posts in PHP:
$result = json_decode( file_get_contents("https://relayapi.autonettv.com/antv/v1/[webtools_domain]/

[api_key]/posts/?limit=5") );

Retrieve all the post for December 2010 (more than 10 if there are more) in PHP:
$result = json_decode( file_get_contents("https://relayapi.autonettv.com/antv/v1/[webtools_domain]/

[api_key]/posts/?start_date=2010-12-01+00:00:00&end_date=2011-01-01+00:00:00&limit=none") );

Retrieving Archives

Listing an archive of post is very common on a blog. By retrieving Archives through RelayAPI you can easily construct a list of archives for your WebTools Content. A request in PHP for archives will look like this:
$result = json_decode( file_get_contents("https://relayapi.autonettv.com/antv/v1/[webtools_domain]/

[api_key]/archive/?parameters") );

Parameters are optional and there is only one parameter for retrieving archives. When parameters are not specified, RelayAPI will return data for you to construct a monthly list of archives:

Name	Description	Default
interval	The interval of time for each item in the archive list. This parameter must be either "month" or "year".	month

Understanding the results of an archive query

The result of the above request will fill the $result variable with an array of objects. Each object will have the following variables:

Name	Description	Type
start_date	The post date of the oldest post in this archive.	Timestamp 2000-01-01 00:00:00
end_date	The post date of the most recent post in this archive.	Timestamp 2000-01-01 00:00:00
title	The title of this Archive, as generated by WebTools.com based on your "interval" setting.	String
post_count	The number of posts in this Archive.	Integer

Retrieving Categories

Listing the categories that have been posted to by an account is very common on a blog. By retrieving Categories through RelayAPI you can easily construct helpful links for your customers. A request in PHP for categories will look like this:
$result = json_decode( file_get_contents("https://relayapi.autonettv.com/antv/v1/[webtools_domain]/

/[api_key]/category/") );

Unlike the requests for posts, the request to retrieve categories does not need any parameters. It will always return the full list of all categories that are being used by this account.

Understanding the results of a category query

The result of the above request will fill the $result variable with an array of objects. Each object will have the following variables:

Name	Description	Type
category_id	The unique ID of this category. If this is the "uncategorized" category, this will be null.	Integer
category_name	The name of this category. If this is the "uncategorized" category, this will be null	String
post_count	The number of posts in this category.	Integer

The Theory Behind WebTools

You do not want your site to simply link to your RelayAPI URL, rather you want your server to read the content from RelayAPI and display only the content from RelayAPI. This can be done by ensuring that all of you links you generate always call back to your website

Examples

An Javascript example is provided using 100% Javascript and HTML. No server side services are needed. The same techniques used in the example can be used in PHP, Java, etc. This example also uses JQuery, which is a low profile Javascript library to expedite some functions. JQuery is an open source project and is released under the MIT license.https://jquery.org/license/.

You need to only change the webtools_domain and the api_key variables in relayapi-setup.js to watch the RelayAPI work. The Javascript based example is for purposes of demonstration only! It is not recommended to use this method for production!!!

An PHP example is provided using PHP and HTML. Your server must be using at least PHP 5.2. You need to only change the $webtools_domain and the $api_key variables in php/relayapi-setup.php to watch the RelayAPI work.

PHP File descriptions:

relayapi-example.css - The file used for formatting the display of the data.

relayapi-help.html - This file

relayapi-setup.php - This contains the variables/parameters that are needed to access the server. You need to only change the $webtools_domain and the $api_key in this file.

relayapi-core.php - This contains the methods/functions used to retrieve the data from the server.

List of functions and their purpose:

getCategories() - retrieves the Categories and returns an array. Please review Understanding the results of a category query

getArchives($interval = "month") - retrieves the Archives either by 'month' (default) or 'year' and returns an array. Please review Understanding the results of an archive query

getArticles($category_id = null, $aindex = null) - retrieves a list of Articles/Posts based on a provided Category ID or an Archive title and returns them in an array. Please review Understanding the results of a post query This has additional global parameters such as page_size (which can be set in the file) and page_num (which is determined by parameters from the url).

getArticle($post_id = null) - retrieves an Article/Post from the server and returns an array defining the article. Please review Understanding the results of a post query

relayapi-display.php - This contains the methods/function to format the data for display.

List of functions and their purpose:

showCategories() - retrieves the Categories and displays them. This will format and display the Categories where the function is placed.

showArchives($interval) - retrieves the Archives either by 'month' (default) or 'year' and displays them. This will format and display the Archives where the function is placed.

showArticles($category_id, $aindex) - retrieves a list of Articles/Posts based on a provided Category ID or an Archive title and displays them. This will format and display the Articles/Posts where the function is placed.

showArticle($post_id) - retrieves an Article/Post from the server and displays it. This will format and display the Article/Post where the function is placed.

relayapi-example.php - A very basic example of how to locate/position the formatted data.

relayapi-example-2.php - An alternate example of how to locate/position the formatted data.

RelayAPI Example html

RelayAPI Example php

Complete RelayAPI help and examples

Previous article: Edit and Customize Your Website and Add Your Logo

Next article: Share or Post Articles to Social Media (Facebook, Twitter, etc)

This article was helpful for 2 people. Is this article helpful for you?

Customer support service by UserEcho