Webservice

Introduction

Webservice (previously Entry API) is a module that creates a REST/XMLRPC/SOAP server under the hood of the ExpressionEngine CMS. It support out of the box a Entry API with support for third party addons (Grid, Matrix, Playa, Relationship etc...). Additional you can extend the API with other APIs like;Comments, Categories, Channels etc...

Documentation versions

Installation

Prerequisites

Make sure your system meets the minimum requirements:

Installation Instructions

Need the EE2 documentation, click here

as for version 5.2.0 there will be no further development on EE2

need the EE 3,4,5 version, you can download this one from the legacy folder (ee_webservice-v7.0.6.zip)

License

For every paid addon you need to validate your license in order to activate the module.

On a local environment, like *.dev *.local *.localhost *.test the license is valid for testing and building a new or existing sites. For every other domain, you need to have a valid license.

Process of validating

Once installed, you will asked to enter your license key. When you entered a valid license you can hit the "Save license" button. This will start validating your license and will redirect you to addons.reinos.nl to login into your account. You can also register a new account in this process.

Control panel overview

Once logged in, you are asked to use your current account or to login with another one.

Control panel overview

Using the current logged in account, the server will check all info related to your license and once valid, it will redirect you back to your site where you see either a success message or an error message.

Control panel overview

License field

This module is using a license field to check if the license for the module is valid or not. On addons.reinos.nl you can check your license and add your valid domains.

Control panel overview

In the Module CP you can enter then your license Control panel overview

When you enter a wrong license, the module will not work and it shows you an warning Control panel overview

Invalid license

Sometimes it happens that the license system says you have an invalid license. When this happens, make sure you have entered your domain url in your account, next to your license on addons.reinos.nl.

If this will not fix your license problem, please contact us on https://addons.reinos.nl/support

The settings

Preference Setting

License key The license key given by Devot-ee

Report Statistics

Report anonymously PHP and EE versions

Free API(s)

This are methods that are free to use, without any login

IP Blacklist

Blacklist an IP

Url Trigger

The trigger when calling the webservice

Super Admin API Key

The super admin API key. With this key you can login as super admin.

Rest output header

Set the output header for the rest service, handy in some cases with "access control allow origin" issues.

Strict site_id

Handle strict usage for site_ids

Debug

Enable the debug mode

Creating Members for the API

  1. Go to the module home
  2. Click on 'Add member'
  3. Select the member
  4. Select the connection type
  5. Choose your API(s)
  6. Ss the server active
  7. Set the logging
  8. Set the debug mode
  9. Save the channel settings
  10. Now you can connect with the url (shown on you details page) of the service.

title

Key / Secret

The key and secret are designed to setup a simple authentication with a key and secret combination.

When a user is created in the webservice module, the module create automatically a key and secret combination. These values cannot be changed and are unique for every user.

Shortkey can be added on the member API page.

title

The following approach can be achieved for example the REST service

http://domain.com/webservice/rest/read_entry?auth[key]=881ffcf82e41db00c3f00710f467e818&auth[secret]=76a7646899af288589c4b69be484879e&data[entry_id]=1

Logging

Each call can be logged via the logging manager that comes with the Webservice module.

The setting can be found on the member detail page title

The overview page can be found in the menu of the Webservice module

title

Note: Make sure you have the logging set to on in your EE settings page

Shortkeys

The Shortkeys are designed to give easy access through an Key. The shortkey is just an easy access instead of username and password

Shortkey can be added on the member API page.

title

title

The following approach can be achieved for example the REST service

http://domain.com/webservice/rest/read_entry?auth[shortkey]=testkey&data[entry_id]=1

Testing Tool

The Webservice module will also comes with a fully featured testing tool to test your API. The Testing Tool is located within the CP of the Webservice module

Navigate to the CP of the Webservice module and click on 'Testing tools'

title

When you clicked on the Testing Tools button, you will navigated to the start page where you have the option for an API.

title

By selecting one of this API`s, you will go to the testing page for this specific API. For example the Entry API

title

By the Entry API you will also notice that there is an extra field "extra", this field will accept an PHP array to extend the fields. In case you want to test your own custom fields.

Adding an Playa field.

array(
    'playa' => array(
        2,3,4,5
    ),
);

You will also notice that all services can be tested, be awere that you need the SOAP extension for the SOAP API.

Urls

The following urls are used for the service

XMLRPC

domain.com/index.php/webservice/xmlrpc

SOAP

domain.com/index.php/webservice/soap (service only)
domain.com/index.php/webservice/soap?wsdl (wsdl only)

REST

The REST service has an intelligence for posting via GET POST PUT DELETE to an endpoint (name of the API, e.g. entry channel etc) or just call the method_name as endpoint. For some API's you only can use the method_name via an GET POST action.

HTTP Actions

domain.com/index.php/webservice/rest/<api_name>/<output>

According to the methods of an API, there are most of the time CRUD methods available (check the api for the methods). Based on the HTTP action GET POST PUT DELETE the module will check what api_name you using and translate the HTTP action to read_ create_ update_ delete_

So for example, using the url domain.com/index.php/webservice/rest/entry/json and make an POST request to this url, will result in an create_entry call.

See the table below how the HTTP actions are translated to the method of your api_name |HTTP action|Method| |---|---| |GET|read| |POST|create| |PUT|update| |DELETE|delete|

Get url

Just a simple way of query the url based on GET values.

Auth via header in a REST request via the following key for auth: "webservice_auth_[field_name]" data: "webservice_data_[field_name]"

User rights

All kind of rights and restrictions can as usually be managed in the Control Panel for the membergroups. This module will grab it from there. There will be also a check on the fields that are required.

API Adman

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

show_adman

Short name Description
group the name of the group Required
limit The limit Optional
order The order of the list Optional

Response

Array
(
    [group_id] => 1
    [group_title] => 1
    [group_url] => http://google.nl
    [site_id] => 1
    [adgroup_id] => 1
    [ad_id] => 1
    [sort_order] => 0
    [ad_title] => just a title
    [ad_image] => url_to_image.png
    [ad_remote_image] => null
    [ad_url] => http://google.nl
    [ad_alt] => just an alt text
    [ad_text] => Just a text
    [ad_start] => 2014-08-23 00:00:00
    [ad_end] => 2015-08-23 00:00:00
    [ad_width] => 0
    [ad_height] => 0
    [ad_max_click] => 9999
    [ad_max_impression] => 99999
    [client_id] => 1
    [ad_impression] => 12
    [ad_clicks] => 0
    [ad_cpc] => 0.00
    [total_results] => 1
    [is_flash] => 0
)

Hooks

webservice_show_adman_start

(added in v3.5)

ee()->extensions->call('webservice_create_category_start', $post_data);

webservice_show_adman_end
(added in v3.5)

ee()->extensions->call('webservice_create_category_end', $return_data);

API Auth

Compatibility

Installation

The Auth API comes natively with Webservice module.

Methods

authenticate

Short name Description
username Your username Required
password Your password Required
new_session Create a new session Optional

Request

$client = new SoapClient('your-domain.com/index.php/webservice/soap?wsdl', array('trace' => 1));

$session_data = $client->authenticate_username('testUsername', 'testPassword');

print_r($session_data);

Request (new session)

$client = new SoapClient('your-domain.com/index.php/webservice/soap?wsdl', array('trace' => 1));

$session_data = $client->authenticate_username('testUsername', 'testPassword', 'yes');

print_r($session_data);

authenticate_username

This is an alias for authenticate

API Category

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_category

Short name Description
group_id The group id Required
parent_id The parent category id Optional
cat_name The category name Required
cat_description The category description Optional
cat_order The order id Optional
custom_field Any custom field Optional

Request

Array
(
    [group_id] => 1
    [parent_id] => 1 
    [cat_name] => test category
    [cat_description] => test description
)

read_category

Short name Description
cat_id The category id Optional
cat_url_title The category url_title Optional
group_id The Group ID Optional
site_id THe site ID Optional
include_cat_group_id If set with any kind of value, the category group is included Optional
include_entries_id If set with any kind of value, the entries associated with the category are included Optional

Request

Array
(
    [cat_id] => 2
)

update_category

Short name Description
cat_id The category id Required
group_id The group id Optional
parent_id The parent category id Optional
cat_name The category name Optional
cat_description The category description Optional
cat_order The order id Optional
custom_field Any custom field Optional

Request

Array
(
    [cat_id] => 1
    [group_id] => 1
    [parent_id] => 1 
    [cat_name] => test category
    [cat_description] => test description
    [cat_order] => 3
)

delete_category

Short name Description
cat_id The id of the category Required

Request

Array
(
    [cat_id] => 2
)

Hooks

webservice_create_category_end

(added in v2.2)

ee()->extensions->call('webservice_create_category_end', $category_id);

webservice_read_category_end

(added in v2.2)

ee()->extensions->call('webservice_read_category_end', $category_data);

webservice_update_category_end

(added in v2.2)

ee()->extensions->call('webservice_update_category_end', $category_data);

webservice_delete_category_end

(added in v2.2)

ee()->extensions->call('webservice_delete_category_end', '');

API Category Group

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_category_group

Short name Description
group_name The group name Required
exclude_group 0=none, 1=Channel Assignment, 3=File Assignment Optional
field_html_formatting none, safe or all Optional
can_edit_categories a membergroup ID Optional
can_delete_categories a membergroup ID Optional

Request

Array
(
    [group_name] => Test group
    [exclude_group] => 0
    [field_html_formatting] => all
    [can_edit_categories] => 6
    [can_delete_categories] => 6
)

read_category_group

Short name Description
group_id The group id Required
show_children Get also all category children Optional

Request

Array
(
    [group_id] => 2
    [show_children] => yes
)

update_category_group

Short name Description
group_id The id of the group Required
group_name The group name Optional
exclude_group 0=none, 1=Channel Assignment, 3=File Assignment Optional
field_html_formatting none, safe or all Optional
can_edit_categories a membergroup ID Optional
can_delete_categories a membergroup ID Optional

Request

Array
(
  [group_id] => 14  
  [group_name] => Test group
  [exclude_group] => 0
  [field_html_formatting] => all
  [can_edit_categories] => 6
  [can_delete_categories] => 6
)

delete_category_group

Short name Description
group_id The id of the group Required

Request

Array
(
  [group_id] => 14  
)

Hooks

webservice_create_category_group_end

(added in v2.2)

ee()->extensions->call('webservice_create_category_group_end', $category_group_id);

webservice_read_category_group_end

(added in v2.2)

ee()->extensions->call('webservice_read_category_group_end', $category_group_data);

webservice_update_category_group_end

(added in v2.2)

ee()->extensions->call('webservice_update_category_group_end', $category_group_data);

webservice_delete_category_group_end

(added in v2.2)

ee()->extensions->call('webservice_delete_category_group_end', '');

API Channel

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_channel

Short name Description
site_id The site ID Required
channel_title The channel title Required
channel_name The channel name Required
url_title_prefix The url prefix Optional
comment_expiration The comment expiration date Optional
status_group Status group ID Optional
field_group Field group ID Optional
channel_url The channel url Optional
channel_lang Language of the channel Optional
group_order Order position Optional

Request

Array
(
    [site_id] => 1
    [channel_title] => Test Channel
    [channel_name] => test_channel
)

read_channel

Short name Description
channel_id The channel ID Required

Request

Array
(
    [channel_id] => 1
)

update_channel

Short name Description
channel_id The channel ID Required
channel_title The channel title Optional
channel_name The channel name Optional
url_title_prefix The url prefix Optional
comment_expiration The comment expiration date Optional
status_group Status group ID Optional
field_group Field group ID Optional
channel_url The channel url Optional
channel_lang Language of the channel Optional
group_order Order position Optional

Request

Array
(
    [channel_id] => 1
    [channel_title] => Test Channel
    [channel_name] => test_channel
)

delete_channel

Short name Description
channel_id The channel ID Required

Request

Array
(
    [channel_id] => 1
)

Hooks

webservice_create_channel_end

(added in v3.0)

ee()->extensions->call('webservice_create_channel_end', $channel_id);

webservice_read_channel_end

(added in v3.0)

ee()->extensions->call('webservice_read_channel_end', $channel_read_data);

webservice_update_channel_end

(added in v3.0)

ee()->extensions->call('webservice_update_channel_end', $channel_update_data);

webservice_delete_channel_end

(added in v3.0)

ee()->extensions->call('webservice_delete_channel_end', $channel_id);

API Comment

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_comment

Short name Description
comment The Comment Required
member_id The Member ID Required
name The Name Required (if no member_id is given)
email The email address Required (if no member_id is given)
location The member Location Optional
url A valid Url Optional

Request

Array
(
  [comment] => a nice comment
  [member_id] => 1
)

read_comment

Short name Description
comment_id The comment ID Required

Request

Array
(
  [comment_id] => 43
)

create_comment

Short name Description
comment_id The Comment ID Required
comment The Comment Optional
name The Name Optional
email The email address Optional
location The member Location Optional
url A valid Url Optional

Request

Array
(
  [comment_id] => 43
  [comment] => an update for the comment
)

Currently not available: Assign comment to another entry ID

delete_comment

Short name Description
comment_id The comment ID Required

Request

Array
(
  [comment_id] => 43
)

API Config

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

read_config

Short name Description
key The config key Required

Request

Array
(
  [key] => url_title
)

API Entry

Compatibility

Installation

The Auth API comes natively with Webservice module.

Methods

create_entry

Short name Description
channel_name The name of the channel where the entry must be inserted Required
title The title for the entry Required
status The status of the entry Optional
allow_comments Allow comments? Optional
sticky Is the entry sticky? Optional
custom_fields Any custom fields can be added Optional
category array of category ids Optional
member_id member_id Optional, otherwise this is the logged user

Request

Array
(
  [status] => Closed
  [title] => Test entry
  [sticky] => y
  [allow_comments] => n

  //custom fields
  [news_body] => This is a full body text
  [news_extended] => This is some small text

  [category] => Array(
    1,2,3,4
  )

  [custom_file_field] => Array(
      'filedata' => base64_encode(file_get_contents('path_to_image.jpg')),
    'filename' => 'filename.jpg',
    'dir_id' => 6
  )
)

read_entry

See search_entry method because of v3.5 they are the same

update_entry

Short name Description
entry_id The entry ID of the entry that you are going to update Required
search[] You can also identify the entry with a search param (See https://docs.reinos.nl/webservice/#search-mechanism) Required
title The title for the entry Optional
status The status of the entry Optional
allow_comments Allow comments? Optional
sticky Is the entry sticky? Optional
custom_fields Any custom field(s) Optional
category array of category ids Optional
member_id member_id Optional, otherwise this is the logged user

Request with ENTRY_ID

Array
(
  [entry_id] => 1
  [status] => Closed
  [title] => Test entry
  [sticky] => y
  [allow_comments] => n

  //custom fields
  [news_body] => This is a full body text
  [news_extended] => This is some small text
)

Request with SEARCH When you are using the search param, The webservice will return an error if multiple errors are found. To ignore this error you can use the force param.

Please note that updating by Entry_id is safer, but it will cost you an extra request.

Array
(
  [search] => Array
  (
    [custom_field] => =test // = sign is for an explicit search. See the https://docs.reinos.nl/webservice/#search-mechanism for more info
    [force] => true // marked that in case of mulitple entries, you will update the first one.
  )
  [status] => Closed
  [title] => Test entry
  [sticky] => y
  [allow_comments] => n

  //custom fields
  [news_body] => This is a full body text
  [news_extended] => This is some small text
)

delete_entry

Short name Description
entry_id The entry ID Required

Request

Array
(
    [entry_id] => 14
)

search_entry

Note: the order of the request will be the order of the query

Short name Description
channel If you use only the channel_name you wil get all entries in this channel Optional
channel_id Search on Channel ID Optional
limit The limit, can be used in conjunction with the offset Optional
offset the offset, can be used in conjunction with the limit Optional
custom_fields any other custom field Optional
orderby sorting data based on a field Optional
sort set the sort Optional
entry_id If selecting just one entry by entry_id Optional
url_title Search on an URL Title Optional
status The status of an entry Optional
grid_field/matrix_field Search in any grid/matrix field with the regular search Optional
grid_field[col_name]/matrix_field[cell_name] Search in any grid/matrix cell where you can search on an exact col_name/cell_name with the use of the search mechanism below Optional
output_fields specify the field to output (applied also on the relationships) Optional
search_all Magic keyword that will search in all entry custom fields Optional
start_on give a date to start from Optional
stop_before give a date to stop before Optional
cat:[field_name] search on category fields (values are cat_id group_id cat_name cat_url_title your_custom_field) Optional
include include more data in the result data[include]=channel|categories|author Optional
return To return only the stats, use this param data[return]=meta Optional
Search mechanism
Basic
Type Operator Example
Contains <empty> data[body]=test
Contains with wildcard <empty> data[body]=~test what result in %test
Contains NOT <empty> data[body]=not test
"Exact" Matching = data[body]==test
Numeric Matching < > <= >= data[body]=>10
Including / Excluding Empty Fields IS_EMPTY data[body]=IS_EMPTY
Including / Excluding Empty Fields NOT IS_EMPTY data[body]=not IS_EMPTY
OR / AND

By default we build the query with AND. To change this to OR, simply add or to a value.

data[title]=or john
Multiple values

To use multiple values for a field, just use a pipeline | or a comma ,

AND values for the same field are not possible due EE limitation

data[title]=test|john

will be in MySQL

title = 'test' OR title = 'john'
Groups

You can also using to group values together like you can do in a normal Database query (field_1 = '4' OR field_1 = '5') AND (field_1 = '2' OR field_1 = '3'')'

AND values for the same field are not possible due EE limitation

Group name can be anything, it should be unique so you can create multiple groups

Request group

data[group_one_name_just_pick_one][group_and][][title]=test|john&ata[group_two_name_just_pick_one][group_and][][title]=willem|doe
(title = 'test' OR title = 'john') AND (title = 'willem' OR title = 'doe')

Request

Array
(
  [channel] => news_channel
  [limit] => 25
  [offset] => 5
  [start_on] => 01-01-2015
  [stop_before] => 31-12-2015
)
Array
(
  [channel] => news_channel
  [limit] => 25
  [offset] => 5
  [start_on] => 01-01-2015
  [stop_before] => 31-12-2015
  [group_and] => Array
  (
    [group_title] => Array
    (
        [0] => Array
        (    
            [title] = john,doe       
        )
    )
  )
)

Hooks

webservice_create_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_create_entry_start', $entry_data);

webservice_create_entry_end

(added in v2.2)

ee()->extensions->call('webservice_create_entry_end', $entry_id, $post_data);

webservice_read_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_read_entry_start', $entry_data);

webservice_read_entry

(added in v4.4.2)
Runs after the validation

$entry_data = ee()->extensions->call('webservice_read_entry', $entry_data, $post_data);

webservice_read_entry_end

(added in v2.2)

$entry_data = ee()->extensions->call('webservice_read_entry_end', $entry_data);

webservice_update_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_update_entry_start', $entry_data);

webservice_update_entry

(added in v4.4.2)
Runs after the validation

$entry_data = ee()->extensions->call('webservice_update_entry', $entry_data, $post_data);

webservice_update_entry_end

(added in v2.2)

ee()->extensions->call('webservice_update_entry_end', $entry_data, $post_data);

webservice_delete_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_delete_entry_start', $entry_data);

webservice_delete_entry_end

(added in v2.2)

ee()->extensions->call('webservice_delete_entry_end', '');

(added in v4.0)
With this hook you can extend the search by your own. Just make sure the hook will return an array of entry_ids.

$entry_ids = ee()->extensions->call('webservice_search_entry_per_entry', $values, $fields);

webservice_search_entry_per_entry

(added in v3.2)

$entry_data = ee()->extensions->call('webservice_search_entry_per_entry', $entry_data);

webservice_search_entry_per_entry

(added in v3.2)

$entry_data = ee()->extensions->call('webservice_search_entry_per_entry', $entry_data);

webservice_search_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_search_entry_start', $entry_data);

webservice_search_entry_end

(added in v2.2)

$entry_data = ee()->extensions->call('webservice_search_entry_end', $entry_data);

webservice_entry_row

(added in v3.5)
WIll be called when reading an entry

$entry_data = ee()->extensions->call('webservice_entry_row', $entry_data);

webservice_read_entry_matrix

(added in v4.0)

ee()->extensions->call('webservice_read_entry_matrix', $value, $col_settings);

webservice_read_entry_grid

(added in v4.0)

ee()->extensions->call('webservice_read_entry_grid', $value, $col_settings);

Examples

Create entry SOAP

<?php

//file data
$image = 'file.jpg';
$file = base64_encode(file_get_contents($image));

$client = new SoapClient('http://domain.com/index.php/webservice/soap?wsdl', array('trace' => 1));

$reponse = $client->create_entry(array(
    'username' => 'testUsername',
    'password' => 'testPassword'
), array(
    'channel_name' => 'news',
    'status' => 'Open',
    'title' => 'test entry',
    'sticky' => 'y',
    'allow_comments' => 'n',
    'category' => '1|2|3',
    'filefield' => array(
        'filedata' => $file,
        'filename' => 'file.jpg',
        'dir_id' => 6
    )
));
?>

Create entry REST (with an image)

<?php
$url = 'http://domain.com/index.php/webservice/rest/create_entry';

//set POST variables
$fields = array(
    'auth' => array(
        'username' => 'admin',
        'password' => 'test123',
    ),
    'data' => array(
        'channel_name' => 'test_channel',
        'title'    => 'Test entry',
    )
);

//open connection
$ch = curl_init();
//set the url, number of POST vars, POST data
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, count($fields));
curl_setopt($ch,CURLOPT_POSTFIELDS, urldecode(http_build_query($fields)));
//execute post
$result = curl_exec($ch);
//close connection
curl_close($ch);

?>

Create entry XMLRPC

<?php
//http://gggeek.github.io/phpxmlrpc/
include("xmlrpc/xmlrpc.inc");

$c = new xmlrpc_client('http://domain.com/index.php/webservice/xmlrpc');

$x = new xmlrpcmsg('create_entry', array(
    php_xmlrpc_encode(array(
        'username' => 'admin',
        'password' => 'test123',
    )),
    php_xmlrpc_encode(array(
        'channel_name' => 'test_channel',
        'title'    => 'Test entry',
    )),
));

$c->return_type = 'phpvals';
$r =$c->send($x);
?>

API Mailing List

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_mailinglist

Short name Description
list_name The short name Required
list_title The title Required

Request

Array
(
    [list_name] => test_mailinglist
    [list_title] => Test Mailinglist
)

read_mailinglist

Short name Description
list_id The list id Required

Request

Array
(
    [list_id] => 2
)

update_mailinglist

Short name Description
list_id The id of the mailinglist Required
list_name The short name Optional
list_title The title of the list Optional
list_template The template of the list Optional

Request

Array
(
  [list_id] => 14  
  [list_name] => test_group
)

delete_mailinglist

Short name Description
list_id The id of the mailinglist Required

Request

Array
(
  [list_id] => 14  
)

create_subscription

Short name Description
list_id The id of the mailinglist Required
email The email Required

Request

Array
(
  [list_id] => 14  
  [email] => test@example.com  
)

delete_subscription

Short name Description
list_id The id of the mailinglist Required
email The email Required

Request

Array
(
  [list_id] => 14  
  [email] => test@example.com  
)

Hooks

webservice_create_mailinglist_start

(added in v1.0)

$post_data = ee()->extensions->call('webservice_create_mailinglist_start', $post_data);

webservice_create_mailinglist_end

(added in v1.0)

ee()->extensions->call('webservice_create_mailinglist_end', $list_id);

webservice_read_mailinglist_start

(added in v1.0)

$post_data = ee()->extensions->call('webservice_read_mailinglist_start', $post_data);

webservice_read_mailinglist_end

(added in v1.0)

ee()->extensions->call('webservice_delete_category_group_end', $list_id);

webservice_update_mailinglist_start

(added in v1.0)

$post_data = ee()->extensions->call('webservice_update_mailinglist_start', $post_data);

webservice_update_mailinglist_end

(added in v1.0)

ee()->extensions->call('webservice_update_mailinglist_end', $list_id);

webservice_delete_mailinglist_start

(added in v1.0)

$post_data = ee()->extensions->call('webservice_delete_mailinglist_start', $post_data);

webservice_delete_mailinglist_end

(added in v1.0)

ee()->extensions->call('webservice_delete_mailinglist_end', $list_id);

webservice_create_subscription_start

(added in v1.0)

$post_data = ee()->extensions->call('webservice_create_subscription_end', $post_data);

webservice_create_subscription_end

(added in v1.0)

ee()->extensions->call('webservice_create_subscription_end', $list_id);

webservice_delete_subscription_start

(added in v1.0)

$post_data = ee()->extensions->call('webservice_delete_subscription_start', $post_data);

webservice_delete_subscription_end

(added in v1.0)

ee()->extensions->call('webservice_delete_subscription_end');

API Member

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_member

Short name Description
group_id The group ID Required
username Required
screen_name Required
password Required
email Required
url Optional
location Optional
bio Optional
language Optional
timezone Optional
date_format Optional
time_format Optional
include_seconds Optional
bday_y Optional
bday_m Optional
bday_d Optional
occupation Optional
interests Optional
aol_im Optional
icq Optional
yahoo_im Optional
msn_im Optional
custom_fields Optional

Request

Array
(
    [group_id] => 2
    [username] => test user
    [screen_name] => Test User
    [password] => du*7e2O
    [email] => info@test.com
)

read_member

Short name Description
member_id The member ID Required

Request

Array
(
    [member_id] => 2
)

search_member

Short name Description
member_id The member ID Optional
group_id The member email Optional
email The member email Optional
screen_name The member screen_name Optional
username The member username Optional

Request

Array
(
    [email] => 'test@example.com'
)

update_member

Short name Description
member_id The member ID Required
screen_name Optional
email Optional
url Optional
location Optional
bio Optional
language Optional
timezone Optional
date_format Optional
time_format Optional
include_seconds Optional
bday_y Optional
bday_m Optional
bday_d Optional
occupation Optional
interests Optional
aol_im Optional
icq Optional
yahoo_im Optional
msn_im Optional
custom_fields Optional

Request

Array
(
    [member_id] => 2
    [msn_im] => jan0292
)

Limitation:

Password and username update has been disabled due some EE complexity

delete_member

Short name Description
member_id The member ID Required

Request

Array
(
    [member_id] => 2
)

Hooks

the default EE hooks are being used.

API Member Group

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_member_group

Short name Description
site_id The site ID Required
group_title Required
group_description Optional
search_flood_control Optional
prv_msg_send_limit Optional
prv_msg_storage_limit Optional
channels Assigned channels (pipeline seperated) Optional
modules Assigned modules (pipeline seperated) Optional
template_groups Assigned template_groups (pipeline seperated) Optional
is_locked Optional
can_view_offline_system Optional
can_view_offline_system Optional
can_access_cp Optional
can_access_content Optional
can_access_publish Optional
can_access_edit Optional
can_access_files Optional
can_access_fieldtypes Optional
can_access_design Optional
can_access_addons Optional
can_access_modules Optional
can_access_extensions Optional
can_access_accessories Optional
can_access_plugins Optional
can_access_members Optional
can_access_admin Optional
can_access_sys_prefs Optional
can_access_content_prefs Optional
can_access_tools Optional
can_access_comm Optional
can_access_utilities Optional
can_access_data Optional
can_access_logs Optional
can_admin_channels Optional
can_admin_upload_prefs Optional
can_admin_design Optional
can_admin_members Optional
can_delete_members Optional
can_admin_mbr_groups Optional
can_admin_mbr_templates Optional
can_ban_users Optional
can_admin_modules Optional
can_admin_templates Optional
can_edit_categories Optional
can_delete_categories Optional
can_view_other_entries Optional
can_edit_other_entries Optional
can_assign_post_authors Optional
can_delete_self_entries Optional
can_delete_all_entries Optional
can_view_other_comments Optional
can_edit_own_comments Optional
can_delete_own_comments Optional
can_edit_all_comments Optional
can_delete_all_comments Optional
can_moderate_comments Optional
can_send_email Optional
can_send_cached_email Optional
can_email_member_groups Optional
can_email_mailinglist Optional
can_email_from_profile Optional
can_view_profiles Optional
can_edit_html_buttons Optional
can_delete_self Optional
mbr_delete_notify_emails Optional
can_post_comments Optional
exclude_from_moderation Optional
can_search Optional
can_send_private_messages Optional
can_attach_in_private_messages Optional
can_send_bulletins Optional
include_in_authorlist Optional
include_in_memberlist Optional
include_in_mailinglists Optional
search_flood_control Optional
search_flood_control Optional

Request

Array
(
    [site_id] => 1
    [group_title] => Test group
    [can_view_offline_system] => y
    [can_search] => n
)

read_member_group

Short name Description
group_id The group ID Required

Request

Array
(
    [group_id] => 2
)

update_member_group

Short name Description
site_id The site ID Required
group_id The membergroup ID Required
group_title Required
group_description Optional
search_flood_control Optional
prv_msg_send_limit Optional
prv_msg_storage_limit Optional
channels Assigned channels (pipeline seperated) Optional
modules Assigned modules (pipeline seperated) Optional
template_groups Assigned template_groups (pipeline seperated) Optional
is_locked Optional
can_view_offline_system Optional
can_view_offline_system Optional
can_access_cp Optional
can_access_content Optional
can_access_publish Optional
can_access_edit Optional
can_access_files Optional
can_access_fieldtypes Optional
can_access_design Optional
can_access_addons Optional
can_access_modules Optional
can_access_extensions Optional
can_access_accessories Optional
can_access_plugins Optional
can_access_members Optional
can_access_admin Optional
can_access_sys_prefs Optional
can_access_content_prefs Optional
can_access_tools Optional
can_access_comm Optional
can_access_utilities Optional
can_access_data Optional
can_access_logs Optional
can_admin_channels Optional
can_admin_upload_prefs Optional
can_admin_design Optional
can_admin_members Optional
can_delete_members Optional
can_admin_mbr_groups Optional
can_admin_mbr_templates Optional
can_ban_users Optional
can_admin_modules Optional
can_admin_templates Optional
can_edit_categories Optional
can_delete_categories Optional
can_view_other_entries Optional
can_edit_other_entries Optional
can_assign_post_authors Optional
can_delete_self_entries Optional
can_delete_all_entries Optional
can_view_other_comments Optional
can_edit_own_comments Optional
can_delete_own_comments Optional
can_edit_all_comments Optional
can_delete_all_comments Optional
can_moderate_comments Optional
can_send_email Optional
can_send_cached_email Optional
can_email_member_groups Optional
can_email_mailinglist Optional
can_email_from_profile Optional
can_view_profiles Optional
can_edit_html_buttons Optional
can_delete_self Optional
mbr_delete_notify_emails Optional
can_post_comments Optional
exclude_from_moderation Optional
can_search Optional
can_send_private_messages Optional
can_attach_in_private_messages Optional
can_send_bulletins Optional
include_in_authorlist Optional
include_in_memberlist Optional
include_in_mailinglists Optional
search_flood_control Optional
search_flood_control Optional

Request

Array
(
    [group_id] => 2
    [can_send_email] => n
)

delete_member_group

Short name Description
group_id The group ID Required

Request

Array
(
    [group_id] => 2
)

Hooks

the default EE hooks are being used.

API Template group

Compatibility

Installation

  1. Copy the files to the system/expressionengine/third_party dir
  2. Enable the API from within the Webservice Module

Methods

create_template_group

Short name Description
site_id The site ID Required
group_name The group name Required
group_order Optional
is_site_default Optional

Request

Array
(
    [site_id] => 1
    [group_name] => Test group
    [is_site_default] => n
)

read_template_group

Short name Description
group_id The group ID Required

Request

Array
(
    [group_id] => 2
)

update_template_group

Short name Description
site_id The site ID Required
group_id The group ID Required
group_name The group name Required
group_order Optional
is_site_default Optional

Request

Array
(
    [group_id] => 2
    [is_site_default] => y
)

delete_template_group

Short name Description
group_id The group ID Required

Request

Array
(
    [group_id] => 2
)

Hooks

API Webservice

Manage the webservice members via API calls

Compatibility

Installation

The Webservice API comes natively with Webservice module.

Methods

create_webservice_member

Short name Description
member_id The member ID from EE Required (if membergroup_id is empty)
membergroup_id The membergroup ID from EE Required (if member_id is empty)
services The services Optional
apis The Api's Optional
shortkeys The shortkeys Optional
active Active Optional

Request

Array
(
  [member_id] => 1
  [services] => xmlrpc|soap
  [apis] => entry|category
  [shortkeys] => test_key1|key2
  [active] => 1 //or 0 
)

Response

Array
(
  [message] => 
  [success] => 
  [metadata] => Array
    (
      [key] => your-new-key
      [secret] => your-new-secret
      [id] => the-id
    )
)

read_webservice_member

Short name Description
member_id The member ID from EE Required (if membergroup_id or webservice_member_id is empty)
membergroup_id The membergroup ID from EE Required (if member_id or webservice_member_id is empty)
webservice_member_id The webservice member ID Required (if member_id or membergroup_id is empty)

Request

Array
(
  [member_id] => 1
)

update_webservice_member

Short name Description
member_id The member ID from EE for searching the member Required (if membergroup_id or webservice_member_id is empty)
membergroup_id The membergroup ID from EE for searching the member Required (if member_id or webservice_member_id is empty)
webservice_member_id The webservice member ID for searching the member Required (if member_id or membergroup_id is empty)
services The services Optional
apis The Api's Optional
shortkeys The shortkeys Optional
active Active Optional

Request

Array
(
  [member_id] => 1
  [services] => xmlrpc|soap
  [apis] => entry|category
  [shortkeys] => test_key1|key2
  [active] => 1 //or 0 
)

delete_webservice_member

Short name Description
member_id The member ID from EE Required (if membergroup_id or webservice_member_id is empty)
membergroup_id The membergroup ID from EE Required (if member_id or webservice_member_id is empty)
webservice_member_id The webservice member ID Required (if member_id or membergroup_id is empty)

Request

Array
(
  [member_id] => 1
)

Default Parameters

All API methods, except the Auth API, will accept a default set of values. For example i will take the API method create_entry.

The accpeted parameters are always 2 arrays. The first one is the auth array and the second one is the data array.

Auth array

The auth array has a structure like this:

Array
(
  [username] => test
  [password] => testPassword

  OR

  [shortkey] => y63idklo93

  OR

  [key] => 881ffcf82e41db00c3f00710f467e818
  [secret] => 76a7646899af288589c4b69be484879e


)

The username and password belong together, shortkey and key secret (defined in the cp) are standalone vars.

Data structure

the data structure is a also a associative array, and wil lbe described on the method page.

Extensions

Parent Relationship/Playa

The Relationship/Playa extension will add a new value to the read_entry and search_entry that include the parents of the relationship child.

[ext_playa_parents] => [{"rel_id":"6","parent_entry_id":"5","parent_field_id":"3","order":"0"},{"rel_id":"7","parent_entry_id":"3","parent_field_id":"3","order":"0"}]
[ext_relationship_parents] => [{"rel_id":"1","parent_entry_id":"5","parent_field_id":"4","order":"1"},{"rel_id":"2","parent_entry_id":"3","parent_field_id":"4","order":"1"}]

Structure

The Structure extension will add some extra structure data to the entry array.

[structure] => {"hide_from_nav":"n","hidden":"n","listing_channel_id":"2","listing_channel_name":"news","listings_total":0}

Relationship in Grid/Matrix (DISCONTINUED, native implement)**

Read/convert your Relationship out of an Matrix/Grid field and get the actual entry instead.

Relationship (DISCONTINUED, native implement)**

Convert your relationship field (also Playa) with real entry data instead of entry_ids

morematrixrelations**

Convert the moreMatrixRelations field in an entry

Simple S3 upload Matrix/Grid field**

Read your Simple S3 upload out of an Matrix/Grid field

Fieldtype API

The Webservice module provide a set of API methods to make your fieldtype compatible. In order to develop such funtionality, you have to create a fieldtype first. When you`re done, you can add some of the following functions below.

If your Fieldtype only save the data to the channel_data table, you don`t have to do anything. The Webservice module will support this out of the box. However, if your data need some specific data structure, you have to use this API to make your field compatible with the Webservice module.

You will mostly need the webservice_save webservice_validate and webservice_pre_process

As an example of how Matrix data can be submitted with the Webservice module:

'matrix_field' => array(
    'rows' => array(
        array(
            'cell_1' => 'row 1',
            'cell_2' => 'row 11',
        ),
        array(
            'cell_1' => 'row 2',
            'cell_2' => 'row 22'
        )
    ),
    'trigger_revisions' => 1
);

This data structure will be converted with the fieldtype API to a correct data structure.

Tag Parameters

Below are the Tag Parameters. Those parameters can be used in the tag described above

field_type

Holds the field type

$this->field_type = '';

field_name

Holds the field name

$this->field_name = '';

field_id

Holds the field id

$this->field_id = 0;

field_data

Holds an array of the field data

$this->field_data = array();

field_settings

Holds an array of the field settings

$this->field_settings = array();

post_data

Holds an array with the data posted to the webservie

$this->post_data = array();

channel_settings

channel

Holds the channel settings as an EE3 Model

$this->channel_settings = array();

webservice_save()

Preps the data for saving. or you can save your data to your own fields instead.

$data : null
$is_new : null
$entry_id : 0
return : string

public function webservice_save($data = null, $is_new = false, $entry_id = 0)
{
    return $data;
}

webservice_grid_save()

Preps the data for saving. or you can save your data to your own fields instead.

$data : null
$entry_id : 0
return : string

public function webservice_grid_save($data = null, $entry_id = 0)
{
    return $data;
}


#### webservice_validate()
Validates the field input.

`$data` : `null`   
`$is_new` : `null`   
`return` : `bool`

public function webservice_validate($data = null, $is_new = false) { //$this->validate_error = ''; return true; }


#### webservice_post_save()
Handles any custom logic after an entry is saved.

`$data` : `null`   
`$entry` : `null` *Model object*   
`$entry_id` : `0`   
`return` : `void`

public function webservice_post_save($data = null, $entry = null, $entry_id = 0) {

}


#### webservice_pre_process()
Preprocess the data to be returned. Convert any complex data to a nice string or array. The Webservice will convert any Array to a json string.

`$data` : `null`   
`$free_access` : `false`   
`$entry_id` : `0`   
`return` : `mixed`

public function webservice_pre_process($data = null, $free_access = false, $entry_id = 0) { return $data; }


#### webservice_delete()
Delete field data. Here you can add some additional deletion for your own fieldtype.

`$data` : `null`   
`$entry_id` : `0`   
`return` : `void`

public function webservice_delete($data = null, $entry_id = 0) { } ```

Search in Grid/Matrix cells

The Webservice module has also support for searching in Grid or Matrix cells.

Example Rest

http://domain.com/webservice/rest/search_entry?auth[shortkey]=27dd39e*7d&data[grid][cell_1]=test

As you can see, you only have to use a multi dimensional array to do this.

Example Curl

<?php
$url = 'http://domain.com/index.php/webservice/rest/search_entry';

//set POST variables
$fields = array(
    'auth' => array(
        'username' => 'admin',
        'password' => 'test123',
    ),
    'data' => array(
        'grid' => array(
            'cell_1' => 'test'
        )
    )
);

//open connection
$ch = curl_init();

//set the url, number of POST vars, POST data
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, count($fields));
curl_setopt($ch,CURLOPT_POSTFIELDS, urldecode(http_build_query($fields)));

//execute post
$result = curl_exec($ch);

//close connection
curl_close($ch);

?>

Compatible Addons

Out of the box the the Webservice module support all fieldtypes that save their data to the exp_channel_data table. Other addons that using their own table or do something with files for example are not supported, unless they listed below.

If you found an addon that has no support for the Webservice, you can send me an email.

Grid

Natively: The following syntax is needed.

array(
    'grid' => array(
        'rows' => array(
            array(
                'cell_1' => 'row 1',
                'cell_2' => 'row 11'
            ),
            array(
                'cell_1' => 'row 2',
                'cell_2' => 'row 22'
            ),
        ),
    ),
);

or in a query string

data[grid][rows][0][cell_1]=row 1&data[grid][rows][0][cell_2]=row 11&data[grid][rows][1][cell_1]=row 2&data[grid][rows][1][cell_2]=row 22

Relationship

Natively: The following syntax is needed.

array(
    'relationship' => array(
        2,3,4,5
    ),
);

or in a query string

data[relationship][]=2&data[relationship][]=3&data[relationship][]=4&data[relationship][]=5

Matrix

Natively: he following syntax is needed.

array(
    'matrix' => array(
        'rows' => array(
            array(
                'cell_1' => 'row 1',
                'cell_2' => 'row 11'
            ),
            array(
                'cell_1' => 'row 2',
                'cell_2' => 'row 22'
            ),
        ),
    ),
);

or in a query string

data[matrix][rows][0][cell_1]=row 1&data[matrix][rows][0][cell_2]=row 11&data[matrix][rows][1][cell_1]=row 2&data[matrix][rows][1][cell_2]=row 22

Playa

Natively: The following syntax is needed.

array(
    'playa' => array(
        2,3,4,5
    ),
);

or in a query string

data[playa][]=2&data[playa][]=3&data[playa][]=4&data[playa][]=5

Zoo Visitor

Natively: The following syntax is needed.

On update, you can avoid some values because the Webservice module detect the member based on the entry_id

array(
    'member_account' => array(
        'email' => 'test@test.com',
        'username' => 'John Doe',
        'password' => 'test123',
        'screen_name' => 'John Doe',
        'group_id' => '4',            
    ),
);

Store

Store only adds basic support in the read/search method.

Content Elements

All fields, but not all are converted good (please make a thread here)

Publisher

Webservice is compatible with Publisher

//add the publisher_lang_id to your entry request
array('publisher_lang_id' => 1)

Searching in older then EE 5.1.0 require to add a fix to a core file of EE due a bug. The following need to be added (https://github.com/ExpressionEngine/ExpressionEngine/issues/31#issuecomment-447055294).

diff --git a/system/ee/EllisLab/ExpressionEngine/Service/Model/Query/Select.php b/system/ee/EllisLab/ExpressionEngine/Service/Model/Query/Select.php
index bb5cff9e1b..b789a89bbb 100644
--- a/system/ee/EllisLab/ExpressionEngine/Service/Model/Query/Select.php
+++ b/system/ee/EllisLab/ExpressionEngine/Service/Model/Query/Select.php
@@ -54,11 +54,7 @@ class Select extends Query {
                        $aliases = array_merge(array($this->root_alias), array_keys($withs));
                        foreach ($aliases as $alias)
                        {
-                               if (stripos($alias, ' as ') !== FALSE)
-                               {
-                                       $parts = explode(' ', $alias);
-                                       $alias = end($parts);
-                               }
+                               list($from, $alias) = $this->splitAlias($alias);

                                $class = $this->getClass($alias);
                                if ( ! is_null($class::getMetaData('field_data')))

Changelog

8.1.3 (15-10-2023)

8.1.2 (10-05-2022)

8.1.1 (30-03-2022)

8.1.0 (19-01-2022)

8.0.2 (01-12-2021)

8.0.1 (23-06-2021)

8.0.0 (20-05-2021)

*Note: The latest version for EE5 and lower can be found in the /legacy/ folder.

7.0.6 (20-05-2021)

7.0.5 (01-03-2021)

7.0.4 (02-05-2020)

7.0.3 (23-02-2020)

7.0.2 (01-12-2019)

7.0.1 (30-10-2019)

7.0.0 (31-07-2019)

*Note: MAKE SURE YOU UPDATE THE ADDON TO VERSION 6.3.2 which can be found in the /legacy/ folder.

\Note:** There is a change you will have to validate the license again

*Note:** Because the module has been renamed with a prefix reinos_ there is an update path by simply add the new update to your site and install it. By installing the module, you are disabling the old module that can be deleted afterward. Also note that you have to rename the module calls and hooks with a prefix reinos_

See this article about the rename https://addons.reinos.nl/news/modules-renamed

6.3.2 (06-03-2019)

6.3.1 (07-02-2019)

6.3.0 (19-12-2018)

6.2.3 (26-11-2018)

6.2.2 (09-06-2018)

6.2.1 (11-04-2018)

6.2.0 (09-04-2018)

*Note: you need to add your license key and license email from addons.reinos.nl in order to validate your license and add a valid domain url in your license field on addons.reinos.nl/profile/licenses or the module will not work on a live site. Also make sure you have read the license section in the documentation

6.1.2 (02-04-2018)

6.1.1 (29-03-2018)

6.1.0 (27-03-2018)

* Breaking changes: see the new docs https://docs.reinos.nl/webservice/#search-mechanism for the new search mechanism

6.0.0 (04-12-2017)

5.5.0 (09-11-2017)

5.4.0 (24-08-2017)

5.3.3 (11-07-2017)

5.3.2 (20-06-2017)

5.3.1 (18-02-2017)

5.3.0 (09-09-2016)

5.2.0 (09-08-2016)

5.1.0 (14-06-2016)

5.0.0

4.4.4

4.4.3

4.4.2

4.4.1

4.4.0

4.3.1

4.3

4.2

4.1.3

4.1.2

4.1.1

4.1

4.0

3.5

3.4.1

3.4

3.3.2

3.3.1

3.3

3.2.1

3.2

3.1

3.0

2.2.1

2.2

2.1

2.0.1

2.0

1.2.1

1.2

1.1.2

1.1.1

1.1

1.0