#12

Product support

Get help in the plugin support forum.

Categories

  • Developer Tools
  • Utility

This plugin is a simple but most powerful RESTful API which also has extended features like IP Blacklist and Scheduled Shutdown

RESTful API is the best plugin for automated Imports/Exports from your website. This plugin is not limited by standard rules (like only specific responses). You'll have the best dynamic RESTful API, and you are free to create unlimited Request Mappings.

We added sample codes for querying the API on the bottom of the Documentation page

What is Request Mapping?

Request Mapping is the key to defining your way of importing or exporting the datas for your website. With mapping, you can select and export partial columns of a table with selecting index keys or other keys from related dropdown menu.

IP Blacklist System

This Web Service has an internal IP Blacklist system which supports both IPv4 and IPv6. You can define unlimited IP's or Notations. It supports multiple types of IP Notations. You can add IP Ranges with also Mask bits in CIDR Notation

Scheduled Shutdown

If you need to shutdown API for a specific time (i.e. when planning to an System Maintenance), RESTful API can disable itself when the shutdown time comes, and than re-activate when the time comes to end.

Available Settings

  • Switch on/off API
  • API Log Tracking
  • Allowing Direct Table Access
  • Access with API Administrator Key
  • Unlimited External API Keys (Flexible as your needs)
  • Authenticate API only with User Credentials
  • Changeable Default Response Output Style
  • Changeable Default Response Charset Encoding
  • "JSON_UNESCAPED_UNICODE" Flag Support
  • CDATA Wrappers in XML Support
  • Purgeable API Logs After a Period
  • Scheduled Shutdown based your Server
  • Shutdown API for a Time Interval, than re-activating Setting
  • API IP Blacklist

Detailed Request Mapping Creations

  • URL Parameter "req" for requesting
  • Related Table selection
  • Columns in Response selection for partial responses
  • "Readonly" option for making mapping only accepts "read" and "read_all" requests
  • Allow Requesting with Index Keys for Simplicity
  • Limit Response Results Option (For read_all)
  • Fetch Data Order Option (ASC/DESC)

Request Logs Tracking

  • Log Status (200 for Successful, Specific header for un-successful)
  • Used Method (GET/POST/PUT/DELETE)
  • Time Spent for Request
  • Request URL
  • Browser Info
  • Referer Info
  • Request Captured DateTime
  • Used Key on Request

Dashboard Report Widgets

Dashboard API Statistics

  • Option to show total statistics
  • Option to show detailed statistics

Dashboard API Logs

  • Option to log counts to show
  • Option to filter by GET/POST
  • Option to filter by Status Code
  • Option to filter by Time Spent

Do you need help about something? please do not hesitate to contact us.

Have a suggestion for a new feature to this plugin? We are always eager to hear from you.

Encountered any error, bug or something missing? Write us and we will solve that asap!!

Detailed Changelog

TODOs: (by priority) (after v1.1.5)

  • Trigger related callbacks on Model which related with the currently operating table for EventHandler
  • Relational queries between tables in same mapping
  • Add dashboard widget for events and event logs

Requirements

Demo Backend Account

If you want to examine the detailed backend functionality, please kindly ask for login details.

RESTful API Dashboard Widgets

Components

Simplicity is the ultimate sophistication. -Leonardo da Vinci

There's nothing to do with changing or adding codes or editing layouts. You just need to add RESTful API Component to an empty page which you'll use as API page (i.e. /api page)

Note: Please make sure you added RESTful API Component to an empty page. Component will change the HTTP output Headers, so don't associate API page with any layouts, partials or contents.

How to edit settings?

  • Go to Settings menu
  • Under System tab, you'll find RESTful API configuration page
  • On settings page, all configurations also have enough details under each option.

Settings Details

  • RESTful API Status - You can change the API status for system based. If you use multiple page API, you can change API status by every component's self attribute
  • RESTful API Log Tracking - You can enable or disable tracking api request logs
  • Allow Direct Table Access - This is not a good option but we added for making API full dynamic. This option is experimental for using
  • API Administrator Key - Master key. This key is intended for your usage only. So don't share this key with aynone..
  • External API Keys - You can add unlimited keys for giving out to external usage
  • Authenticate API only with User Credentials - If you want to permit API to only your users, simply activate this option. User credentials should be sent as "api_login" and "api_password" parameters. (Using API Administrator Key or External API Key is faster than User Authentication)
  • Default Response Output Style - You may prefer your users getting response as JSON / XML as default. If there is a "type" parameter in request, output will be override this option
  • Default Response Charset Encoding - You can change output character encoding with this option
  • Add -JSON_UNESCAPED_UNICODE- Flag - JSON_UNESCAPED_UNICODE Flag is useful when API returns thousands (or zillions) of non-Unicode data, or when you prefer "Hello José" to "Hello Jos\u00e9"
  • Add CDATA Wrappers in XML - If you have HTML content in some response columns, you should activate wrapping with CDATA in XML
  • Purge API Logs After - You can define days you wish to purge logs after created
  • Scheduled Shutdown - Place a tick to this option and choose start and end times if you want to shutdown the WebService for specific time interval
  • API IP Blacklist - Enter IP Addresses for disable to request the API. You can write down each IP in a new line

Creating Request Mapping Relations

  • URL Parameter (req) - This parameter should be sent as "req" for using this mapping
  • Related Table - Related table for mapping
  • Columns in Response - Select database columns which you want to return in response to the API users. (ONLY this columns will be shown in response) Be careful not to select sensitive columns
  • Read Only - If this option activated, requests will be accept only "read" and "read_all" parameters. For this table, "Create", "Update" and "Delete" won't work
  • Allow Requesting with Index Keys - If this option activated, API users don't have to send "key" parameter while using "read". API requests can be performed directly with one of the index keys (i.e if indexes are "id" and "email", request may have only "id=2", doesn't need to define "key=id&id=2"). This option is useful when simplicity matters
  • Limit Response Results - You can limit query response when "read_all" operates. Use "0" for no limits
  • Fetch Data Order - Choose "ORDER BY" value for fetching data from database. First index key field of table will be selected (mostly "id")

Usage of Logs Section

You can activate also hidden parameters for listing in API Logs Page. Of course, when you click any log, you can show more details about that request.

Parameters can be shown in listing:

  • Captured Date
  • Request Status
  • Request Method
  • IP Address
  • Time Spent
  • Used Key
  • Is API Activated when Requested
  • Request URL
  • Browser Info
  • Referer Info

Adding IP, IP Block or IP Notations to Blacklist

  • You can enter IP Addresses for disable to request the API. Write down each IP in a new line
  • You can use following rules for IP ranges to block:
    • Direct IP: 1.2.3.4
    • Wildcard format: 1.2.3.*
    • CIDR format: 1.2.3/24 or 1.2.3.4/255.255.255.0
    • Start-End IP format: 1.2.3.0-1.2.3.255

Matching Examples:

Rule Status IP for Matching
80.140.. rule will match IP 80.140.2.2
80.140.*.* rule will NOT match IP 80.141.2.2
80.140/16 rule will match IP 80.140.2.3
1.2.3.0-1.2.255.255 rule will match IP 1.2.3.4
80.140.0.0-80.140.255.255 rule will NOT match IP 90.35.6.12
80.76.201.32/27 rule will match IP 80.76.201.37
80.76.201.32/27 rule will NOT match IP 81.76.201.37
80.76.201.32/255.255.255.224 rule will match IP 80.76.201.38
80.76.201.32/255.255.255.* rule will match IP 80.76.201.39
80.76.201.64/27 rule will NOT match IP 80.76.201.40
192.168.3.0/24 rule will NOT match IP 192.168.1.42
127.0.0.0-129.0.0.0 rule will match IP 128.0.0.0

General Parameters

  • auth = Exists for checking with API Administrator Key config
  • api_login = Exists for authenticating the query with username/email if auth_with_user activated
  • api_password = Exists for authenticating the query with password if auth_with_user activated
  • do = Operation to querying the API endpoint
  • req = Relation name or exact table name if activated
  • key = Custom parameter for defining primary key other than id
  • rules = One or some Where conditionals for filtering the results. Two colon for value separate, one pipe for rule separate like: COLUMN::OPERATOR::VALUE
  • type = Whether response type JSON or XML

Filter Key Maps

Key Operator
lt <
gt >
eq =
neq !=
lteq <=
gteq >=
like like

GET Query samples for API

Method Name Query
GET Fetch one result ?auth=write_api_admin_key&do=read&req=users&id=1&type=xml
GET Fetch all results ?auth=write_api_admin_key&do=read_all&req=users&type=xml
GET Fetch all results with filter ?auth=write_api_admin_key&do=read_all&req=users&rules=COLUMN::OPERATOR::VALUE|id::lt::10|created_at::lt::2016:07:18&type=xml
GET Create new entry ?auth=write_api_admin_key&do=create&req=users&name=John&email=[email protected]&ip=127.0.0.1&type=json
GET Update an existing entry ?auth=write_api_admin_key&do=update&req=users&key=id&id=1&name=Jane&type=json

POST Query samples for API with cURL

cURL - Fetch one result

$getOne =  http_build_query([
    // mandatory fields
    'auth'  => 'write_api_admin_key',
    'do'    => 'read',
    'req'   => 'users',
    'key'   => 'email',
    'email' => [email protected]',
    // optional fields
    'type'  => 'xml'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://demo.uxms.net/api/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $getOne);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$output = curl_exec($ch);

curl_close($ch);
dump($output);

cURL - Fetch all results

$getAll =  http_build_query([
    // mandatory fields
    'auth'  => 'write_api_admin_key',
    'do'    => 'read_all',
    'req'   => 'users',
    // optional fields
    'type'  => 'xml'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://demo.uxms.net/api/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $getAll);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$output = curl_exec($ch);

curl_close($ch);
dump($output);

cURL - Fetch all results with filter

$getAll =  http_build_query([
    // mandatory fields
    'auth'  => 'write_api_admin_key',
    'do'    => 'read_all',
    'req'   => 'users',
    'rules' => 'id::lt::10|created_at::lt::2016:07:18',
    // optional fields
    'type'  => 'xml'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://demo.uxms.net/api/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $getAll);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$output = curl_exec($ch);

curl_close($ch);
dump($output);

cURL - Create new entry

$create =  http_build_query([
    // mandatory fields
    'auth'  => 'write_api_admin_key',
    'do'    => 'create',
    'req'   => 'users',
    // optional fields
    'ip'    => '',
    'name'  => '',
    'email' => '',
    'pass'  => '',
    'type'  => 'xml'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://demo.uxms.net/api/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $create);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$output = curl_exec($ch);

curl_close($ch);
dump($output);

cURL - Update an existing entry

$update =  http_build_query([
    // mandatory fields
    'auth'  => 'write_api_admin_key',
    'do'    => 'update',
    'req'   => 'users',
    'key'   => 'id',
    'id'    => 4,
    // optional fields
    'ip'    => '',
    'name'  => '',
    'email' => '',
    'pass'  => '',
    'type'  => 'xml'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://demo.uxms.net/api/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $update);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$output = curl_exec($ch);

curl_close($ch);
dump($output);

POST Query samples for API with cURL

cURL - Fetch one result

curl -i \
    --request POST 'https://demo.uxms.net/api/' \
    --data 'auth=write_api_admin_key' \
    --data 'do=read' \
    --data 'req=users' \
    --data 'key=email' \
    --data [email protected]' \
    --data 'type=xml'

cURL - Fetch all results

curl -i \
    --request POST 'https://demo.uxms.net/api/' \
    --data 'auth=write_api_admin_key' \
    --data 'do=read_all' \
    --data 'req=users' \
    --data 'type=xml'

cURL - Fetch all results with filter

curl -i \
    --request POST 'https://demo.uxms.net/api/' \
    --data 'auth=write_api_admin_key' \
    --data 'do=read_all' \
    --data 'req=users' \
    --data 'rules=id::lt::10|created_at::lt::2016:07:18' \
    --data 'type=xml'

cURL - Create new entry

curl -i \
    --request POST 'https://demo.uxms.net/api/' \
    --data 'auth=write_api_admin_key' \
    --data 'do=create' \
    --data 'req=users' \
    --data 'name=John' \
    --data [email protected]' \
    --data 'ip=127.0.0.1' \
    --data 'type=xml'

cURL - Update an existing entry

curl -i \
    --request POST 'https://demo.uxms.net/api/' \
    --data 'auth=write_api_admin_key' \
    --data 'do=update' \
    --data 'req=users' \
    --data 'key=id' \
    --data 'id=1' \
    --data 'type=xml'
  • Found the plugin useful on 21 Jul, 2016

    when is the new version coming out? :/ its kinda broken in the latest version of octobercms

  • author

    Replied on 22 Jul, 2016

    We have had very busy with our local customers, so we delayed a bit about new version of the plugin. Sorry about that.

    We are aware of the issues for the plugin with stable release of OctoberCMS and fixed most of all.

    Also we added new features to the plugin and planned to release new version before Jul 27. You can see what's new on the releases of the plugin from https://uxms.net/changelog/restful-api

    Btw, we are always open to new ideas of improvements about all of our plugins and eager to make it useful for all of our valued users. Just send us your ideas with an email or with using contact form.

    Thanks for patience and understanding.

    Have a nice day!

1.1.4

Added "rules" definition for read_all queries. Docs updated

Aug 26, 2016

1.1.3

Plugin SVG icon added for October stable release

Aug 03, 2016

1.1.2

Small fix for plugin menu

Jul 28, 2016

1.1.1

Added permission option for Event Automation page

Jul 28, 2016

1.1.0

!!! Created Event Handler, lots of fixes - See changelog

Jul 28, 2016

1.0.3

Some typos fixed

Jul 28, 2016

1.0.2

Added README.md

Jul 28, 2016

1.0.1

Log deleting statement corrected

Aug 16, 2015

1.0.0

Plugin Init

Aug 16, 2015

Upgrade guide

Upgrading To 1.1 From 1.0

This upgrade notification is intended to inform you if you've made any replacement on code base of the plugin. v1.1 is not deprecated any methods which has defined before.

There are lots of code fixes, typo fixes, optimizations and so far.

You can take a look at the Changelog for all detailed changes for all versions of the plugin.