Book Documentation Cap Tutorials

API

You can interact with your 1202 system from another server through the application programming interface (API). This allows you to get or modify data.

Get data

Any content in your 1202 system can be retrieved. However, you need to explicitly allow who, what and how. This is done through the system settings, content filters and model blocks.

Note: Examples are given in PHP, one of the most popular programming languages for the web. If you use a different language, please refer to the documentation of that language.

System settings

You have to allow every server that wants to retrieve something from your 1202 system. To do this, add the server's IP address to the list of 'Allowed addresses' in the 'General' pane of the 'System' section.

The requests of the remote server could be relayed. In that case, the IP address of the relay is the one you have to add to the 'Allowed addresses'. What counts is the server that ultimately makes the connection to your 1202 system.

To get the IP address of the server that makes the request, you can run this line of code (in PHP) from the remote server:

echo file_get_contents('http://checkip.dyndns.com/');

This will return something like:

Current IP Address: 149.210.170.40

Add this address to the 'Allowed addresses'.

Content filter

In order to select the content you want to allow for retrieval, you need to make content filters. Every item you want to be retrievable has to show up with your filter. Use aliases in your filter to adjust it to a query string.

An example for a filter often used in this context is one for an article based on its 'id'. The query string might look like:

?article-id=1

The 'article-id' value should match the 'id' value of an item in the 'Text' container in your 1202 system. Therefore, the filter should be set up using 'article-id' as alias:

id alias • = article-id

Model block

Models are the intermediaries between your 1202 system and the 'outside'. If you want to retrieve the content described in one of your filters, you have to link that filter to a model block. The filter 'feeds' the data into it before it is retrieved.

Within the block, you can determine how the retrieved content should be outputted. For this, you can use fields and 1202 script.

If, for example, the model block was set up to output a particular article to a website, it could be composed thus:

<h2>{8: Title}</h2>
{9: Text}

For every item 'fed' into the block, it would output the above code, with the field names replaced by the values for these fields as provided by each item. If you wanted the block to output a list of article titles, for instance to fill an index, the code of the block could be:

<p>{8: Title}</p>

Of course, a filter that fetches the items that have to be included should be linked to the block.

As a last example, throwing in some 1202 script to count the items:

$ifelse[{var: count} !=][$var[count][{var: count} + 1]][$var[count][1]]
<p>{var: count}. {8: Title}</p>
$storevar[count]

In the first line, 1202 script sets the variable 'count' to '1' if it isn't set, otherwise increases the value by 1. The second line outputs the count variable and the item title within a paragraph HTML element. The last lines stores the variable so it will retain its value for the next pass.

This could also be simplified to:

<li>{8: Title}</li>

…and on the front-end be put into an ordered list HTML element.

Tip: Model blocks are always retrieved using their id. When viewing the model it belongs to, you can find the id of the block next to the block title.

Request: server-side

Requesting a model block server-side is easy and clean. It is a simple HTTP GET request, like looking up a web page. The syntax of the URL for the request is:

https://[your system name].1202hq.com/block/[id][modifiers]

A request for a system named 'demo' and model block with id '1' in PHP would look like this:

file_get_contents('https://demo.1202hq.com/block/1');

Just echo that out to display it:

echo file_get_contents('https://demo.1202hq.com/block/1');

Using modifiers, or GET variables, to get for example an article by its 'id', simply means adjusting the URL:

echo file_get_contents('https://demo.1202hq.com/block/1?article-id=1');

Be sure to 'alias' the modifiers to actual fields within the linked content filter. You can use as much modifiers as you like.

Request: client-side

When you do not have the option of uploading a script to the server, or want to dynamically load data from the client, you can do it client-side using JavaScript.

To make cross-site requests possible – which happens when a site (server) connects to your 1202 system – you have to utilize a technique called JSONP (JavaScript Object Notation with Padding).

A bit of JavaScript code will make a request to your 1202 system, which will send back a JSON-encoded response. The response is then encoded and displayed or outputted.

A JavaScript library like jQuery makes it easy to do the JSONP trick. Make sure you have jQuery loaded and use the following piece of code:

$.getJSON('https://[your system name].1202hq.com/block/[id]?1202cb=?', function (data) {
    $('#content').append(data);
});

For a system named 'demo' and model block with id '1':

$.getJSON('https://demo.1202hq.com/block/1?1202cb=?', function (data) {
    $('#content').append(data);
});

This appends the data retrieved from your 1202 system to the 'div' HTML element with the id 'content' on your webpage.

For more information, read the jQuery API documentation.

Note: With a client-side request, the device initiating it will provide the 'remote address' which your 1202 system does its access checking on. If client-side requests are made on a public website, make sure to arrange public access in your system settings.

Info: The inclusion of '?1202cb=?' (a 'callback' modifier) in the requested URL is necessary to decode and display the retrieved data.

Modify data

The content in your 1202 system can be changed remotely. Two features are used for this: importing and executable filters.

User

A request to modify requires authorization. You can use an existing user or create a new one to authorize requests. In both cases ensure the user has enough permissions to accommodate the modification requests and check the box next to 'Remote access' when creating or editing the user item.

Info: When modifying data through a POST request, no formal login is made to your 1202 system. This means there is no log entry made.

Tip: If you create a user especially for making remote modifications, make sure you check the box next to 'No browser access' for that user. It diminishes the chance of any abusive actions in case the remote server is compromised.

Request

Modifying data is done through a HTTP POST request. The syntax for the URL is:

https://[your system name].1202hq.com/post

The modifying request has to include the POST values:

  • 1202user: name of the user that authorizes the request.
  • 1202pass: password of the user that authorizes the request.

Also, either or both POST values:

  • 1202data: data to be imported into the system. Has to meet the same requirements as 'normally' imported data, with the exception that values need to be separated by semicolons (instead of either tabs, commas or semicolons).
  • 1202filter: id of the content filter that has to be executed. Executable filters can delete one or more items.

Tip: When importing data and executing a filter, the filter execution will occur first, importing second. This means you can first 'clean up' items and then import new ones. If it should be the other way around, simply make multiple requests.

And finally, optionally, and only when setting the '1202data' value:

  • 1202commit: determines if the data should be saved first (for review) or imported immediately. Set this value to 'true' to immediately import. Defaults to 'false'.

Note: To be able to receive and process remotely submitted data, you have to add the IP address of the sending server to the list of 'Allowed addresses' in the systems settings and the user authorizing the request has to have 'control' permissions for the 'System' section when importing. When remotely executing a filter, the user has to have at least 'write' permissions for the container on which the filter is executed.

cURL

To make the request, you can use cURL (Client URL Request Library). This allows you to send an HTTP POST request to a different server. A simple setup in PHP would be:

$fields = array('1202user' => '[user name]',
                  '1202pass' => '[user password]',
                  '1202commit' => '[true or false]',
                  '1202filter' => '[filter id]',
                  '1202data' => '[import data]');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, '[url]');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_exec($ch);
curl_close($ch);

A 'real world' example could look like this:

$fields = array('1202user' => 'Leonard',
                  '1202pass' => 'numbergod123',
                  '1202commit' => 'true',
                  '1202filter' => '2',
                  '1202data' => 'Text: Title;Text: Text' . "\n" . '"Posted title";"With some posted text!"');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,'https://demo.1202hq.com/post');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_exec($ch);
curl_close($ch);

Tip: Delimit field values with double quotes (as shown in the example above) to avoid an accidental semicolon breaking your import. Always delimit with double quotes when handling user input.