API: Maian Journal Documentation

Overview

The Maian Journal API is a simple, yet powerful function that enables you to post a journal entry from any application.

Data MUST be sent as a HTTP POST and be formatted in JSON. The available parameters are shown below. This is for advanced users. It is always a good idea to send the 'application/json' content type header with your requests. It is also recommended you sent your data over SSL/TLS for security and you verify a trusted connection (see below).

Enable API

To enable the API you need to create an API key in the settings. This must be used in all transmissions and is required to validate incoming posts are genuine.

API Log

Should be enabled when debugging. Activate the API log in your settings. This will write entries to your logs folder. You can refer to this file if you are having issues getting the API to work.

API Post Structure

apikey = API KEY
journal = JOURNAL OPTIONS ARRAY
categories = ARRAY OF CATEGORY IDs

Journal Parameter Options

If some parameters aren't included they will revert to the defaults shown:

staff = 0 or ID number of staff member if applicable. Default: 0
title = Title of Journal. Required.
comms = Journal comments. Required.
encomms = Are comments enabled for this journal? Yes or No value. Default: No
pubts = Publish date/time. Must be valid Unix timestamp. Default: Current date/time
delts = Delete date/time. Must be valid Unix timestamp. Default: 0 (disabled)
metat = Alternative browser title if applicable. Default: ''
slug = Rewrite slug. Must be unique. See note below. Required.
tags = Comma delimited search tags. Default: ''
stick = Pin journal to top of list screens? Yes or No value. Default: No
user = For private journal enter username. Default: ''
pass = For private journal enter password. Default: ''
en = Is this journal enabled? Yes or No value. Default: Yes

More info on this options on the 'Add Journal' page.

For private, both username and password are required. If one is missing, this is ignored.

The ONLY characters allowed for slugs are: hyphens, underscores & alphanumeric. Anything else will be removed or ignored.

Staff ID

You can find the staff IDs on the staff screen in your admin control panel. A 0 (zero) value means the global user who logs in via control/_cfg.php.

Category ID Parameter

Must be an array of one or more valid category IDs. You can view category IDs in your control panel via the categories screen.

Minimal Example (using Curl)

Curl can be used to transmit data to your journal system. Here we use just the minimal required values.

<?php

$data = array(
  'apikey' => 'ABC123-DEF789-KJI098',
  'journal' => array(
    'title' => 'My Super Duper New Journal',
    'comms' => 'Lorem ipsum dolor sit amet consectetuer quis est at felis dui.',
    'slug' => 'lorem-slug-post'
),
'categories' => array(1,2,3)
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/journal/index.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json'
));
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
$r = curl_exec($ch);
curl_close($ch);

print_r(json_decode($r, true));

?>

Advanced Example (using Curl)

This example uses more of the parameter options.

<?php

$data = array(
  'apikey' => 'ABC123-DEF789-KJI098',
  'journal' => array(
    'title' => 'My Super Duper New Journal',
    'comms' => 'Lorem ipsum dolor sit amet consectetuer quis est at felis dui.',
    'slug' => 'lorem-slug-post',
    'pubts => 1482969600,
    'metat => 'My Super Browser Title',
    'tags => 'super,duper,journal',
    'user => 'lonelyradish',
    'pass => '%52#s@xqlzi6tgt'
),
'categories' => array(1,2,3)
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/journal/index.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json'
));
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
$r = curl_exec($ch);
curl_close($ch);

print_r(json_decode($r, true));

?>

If you are using a password it is recommend you transmit across SSL ONLY.

SSL/TLS Certificate Authority Certificates

It is recommended you use Curl to verify a trusted connection. This can be easily done using Curls default CA cert. It can be downloaded here. If used, change your Curl code to:

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_CAINFO, '/home/your-server-path/cacert.pem');

Response Handling

Maian Journal responds with a status parameter of either 'err' or 'ok'. Your application should handle the response accordingly. For 'ok' responses the journal ID is also returned in case you wish to do further actions.

OK example:

{
"status" : "ok",
"id" : "10"
}

Error example:

{
"status" : "err",
"errors" : ""
}

If an error occurs, the errors will be returned pipe delimited in the "errors" parameter. They will also be logged in the API log (see above).

Email Notifications

Email notifications are sent as normal when a journal is entered via the API. If you prefer NOT to have the API send any notifications, but want to keep standard journal notifications on when posted in the control panel, you can deactivate API notifications via the 'ENABLE_API_NOTIFICATIONS' option in the 'control/options.php' file. Set to 0 to disable only API notifications.

define('ENABLE_API_NOTIFICATIONS', 0);

Problems?

Please see the support options.