forked from elioqoshi/phplist-manual
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathch049_api-and-integrations.xhtml
40 lines (39 loc) · 4.19 KB
/
ch049_api-and-integrations.xhtml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><title/></head><body>
<h1 id="api-and-integrations">API and integrations</h1>
<p>phpList is a stand-alone solution which can also be integrated into other systems, workflows, and applications. This can be as simple as automatically adding a sign-up form for a newletter list to your Wordpress blog, or as complex as using phpList as one of many components in a larger automated enterprise resource planning system.</p>
<h2>Application Programming Interface (API)</h2>
<p>phpList 3.4.0 and later includes a <abbr title="Representational State Transfer">REST</abbr> API which, when enabled, allows other software systems to interact with it in a variety of ways, such as managing subscribers, lists, and campaigns.</p>
<h3>System requirements</h3>
<p>The REST API has different server requirements than phpList 3 — it may not be compatible with your environment even if you are already using phpList 3 successfully. The most significant difference is the requirement of PHP 7. Apache users must also have support for <code>.htaccess</code> files enabled in order to use the API securely.</p>
<p>For the full list of requirements please see the <a href="https://github.com/phpList/base-distribution#phplist-4-base-distribution" target="_blank">System Requirements</a> of phpList 4.</p>
<h3>Enable the API</h3>
<ul>
<li>Open the following file with a text editor: <code>public_html/lists/base/config/config_modules.yml</code></li>
<li>Change <code>false</code> to <code>true</code> on the following line: <code>{ view_response_listener: { enabled: false } }</code></li>
<li>Delete this folder entirely: <code>public_html/lists/base/cache</code></li>
</ul>
<h3>Access the API</h3>
<p>By default the base URL for API requests is <code>http://my-website.com/lists/base/public/api/v2/</code>. So, to authenticate a new API session you could use following URL: <code>http://my-website.com/lists/base/public/api/v2/sessions</code>. This access URL can be changed by editing your webserver configuration.</p>
<h3>Test the API</h3>
<p>To check if the API is enabled and working properly, you can try authenticating a new session from a Linux or Mac terminal using the <code>curl</code> command-line utility. Substitute the example phpList installation URL, and phpList admin username and password, in the following command, and copy and paste it into your terminal:</p>
<p><code>curl --request POST --url http://my-website.com/lists/base/public/api/v2/sessions --header 'Content-Type: application/json' --data '{"login_name": "admin","password": "phplist"}'</code></p>
<p>The output should be similar to the following, with different expiry date, key, and id:</p>
<p><code>{"expiry":"2019-03-31T18:16:42+00:00","key":"24244871cf45aa2f1c0dbddf82b9912b","id":6}</code></p>
<p>If instead you see a message in HTML stating '403 Forbidden', then you should check your webserver's permission configuration.</p>
<h3>Examples of API clients / implementations</h3>
<p>To demonstrate how to use the API some example clients are available in different programming languages. See the <a href="" target="_blank">REST API Client Examples</a> repository for details.</p>
<h3>Example API clients</h3>
<p>Demo implementations of the API in various languages can be found in the dedicated <a href="https://github.com/phpList/RestAPIclientSimpleExample" target="_blank">repository</a>.</p>
<h3>Enable API logging</h3>
<p>The following steps will enable logging of API requests and errors:</p>
<ul>
<li>Edit the following file: <code>public_html/lists/base/vendor/phplist/core/config/config_prod.yml</code></li>
<li>Remove the pound (<code>#</code>) from the beginning of every line from line 4 onwards to uncomment them</li>
</ul>
<h3>Supported API actions</h3>
<p>For complete documentation of all supported REST API actions please see the <a href="https://github.com/phpList/rest-api/blob/master/docs/Api/RestApi.apib" target="_blank">API Blueprint</a>.</p>
</body>
</html>