Difference between revisions of "REST"

From aMember Pro Documentation
Jump to: navigation, search
 
(19 intermediate revisions by 3 users not shown)
Line 9: Line 9:
 
Once the module is enabled, scroll down and find an admin menu item ''Remote Api Permissions''. Click ''New Record''.&nbsp;You will see a form to fill - your comment about the access key, a generated access key itself, and list of checkboxes describing what system calls is available for given access key. Check necessary calls and Save.<br>  
 
Once the module is enabled, scroll down and find an admin menu item ''Remote Api Permissions''. Click ''New Record''.&nbsp;You will see a form to fill - your comment about the access key, a generated access key itself, and list of checkboxes describing what system calls is available for given access key. Check necessary calls and Save.<br>  
  
 +
= Samples =
 
== Fetching list of users via Web API<br>  ==
 
== Fetching list of users via Web API<br>  ==
  
To try it out, open in your browser ''http://example.com/amember/api/users?_key=''<u>''APIKEY''</u>
+
To try it out, open in your browser ''http://example.com/amember/api/users?_key=APIKEY  
  
 
You will see first 20 user records in JSON&nbsp;format and total number of users in ''_total'' variable  
 
You will see first 20 user records in JSON&nbsp;format and total number of users in ''_total'' variable  
Line 28: Line 29:
 
;_filter[''FIELDNAME'']  
 
;_filter[''FIELDNAME'']  
 
:Adds a WHERE condition for ''FIELDNAME''. If search value contains ''%'' it is considered as pattern for SQL LIKE expression, else SQL = condition is used. If several filters provided, it will be concatenated in SQL AND expression.
 
:Adds a WHERE condition for ''FIELDNAME''. If search value contains ''%'' it is considered as pattern for SQL LIKE expression, else SQL = condition is used. If several filters provided, it will be concatenated in SQL AND expression.
<br>
 
  
;_nested[]
+
;_nested[]  
:Requests to include nested records into dataset. For example, if you are accessing users database via REST, you can do it like this: ''http://example.com/amember/api/users?_key=''<u>''APIKEY''</u>&format=xml&_nested[]=invoices&_nested=access This will include user's invoices and access records into output. List of available nested tables is unique to each record type.
+
:Requests to include nested records into dataset. For example, if you are accessing users database via REST, you can do it like this: <pre>http://example.com/amember/api/users?_key=APIKEY&amp;format=xml&amp;_nested[]=invoices&amp;_nested[]=access</pre> This will include user's invoices and access records into output. List of available nested tables is unique to each record type.
 +
 
 +
== Adding users via Web API<br>  ==
 +
 
 +
To add a customer via Web API, you have to use HTTP POST method. There is a sample call to add a user to database:
 +
<pre>POST /amember/api/users _key=APIKEY&amp;login=apiadded&amp;pass=0000&amp;email=test@example.com&amp;name_f=John&amp;name_l=Smith&amp;_format=xml </pre>
 +
in case of success it will return added user record.
 +
 
 +
== Updating users via Web API<br> ==
 +
 
 +
To update a customer via Web API, you have to either use HTTP PUT method, or make POST and pass _method=PUT parameter with your request. There is a sample call to update a user to database:
 +
 
 +
<pre>PUT /amember/api/users/22
 +
_key=APIKEY&name_f=NewName&pass=1111</pre>
 +
 
 +
in case of success it will return updated user record with first name set to "NewName" and the password set to 1111. Other user fields will be kept untouched. The following call gives the same result:
 +
 
 +
<pre>POST /amember/api/users/22
 +
_method=PUT&_key=APIKEY&name_f=NewName&pass=1111</pre>
 +
 
 +
== Deleting users via Web API<br> ==
 +
 
 +
To remove a customer via Web API, you have to either use HTTP DELETE method, or make POST and pass _method=DELETE parameter with your request. There is a sample call to add a user to database:
 +
 
 +
<pre>DELETE /amember/api/users/22
 +
_key=APIKEY</pre>
 +
 
 +
in case of success it will return deleted user record as look like before deletion.
 +
 
 +
== Complete examples in PHP<br> ==
 +
 
 +
http://www.amember.com/docs/REST_API_examples
 +
 
 +
 
 +
= Available REST Controllers =
 +
 
 +
== Users ==
 +
''http://example.com/amember/api/users?_key=APIKEY
 +
Nested Controllers:
 +
* invoices
 +
* access
 +
 
 +
== Invoices ==
 +
''http://example.com/amember/api/invoices?_key=APIKEY
 +
Nested Controllers (all are enabled by default):
 +
* invoice-items
 +
* invoice-payments
 +
* invoice-refunds
 +
* access
 +
 
 +
== Payments ==
 +
''http://example.com/amember/api/invoice-payments?_key=APIKEY
 +
 
 +
== Refunds ==
 +
''http://example.com/amember/api/invoice-refunds?_key=APIKEY
 +
 
 +
== Products ==
 +
''http://example.com/amember/api/products?_key=APIKEY
 +
Nested Controllers:
 +
* billing-plans
 +
 
 +
== Affiliate Payouts ==
 +
''http://example.com/amember/api/aff-payouts?_key=APIKEY
 +
Nested Controllers:
 +
* aff-payout-details
 +
 
 +
== Affiliate Payout Details ==
 +
''http://example.com/amember/api/aff-payout-details?_key=APIKEY
 +
 
 +
==  Product Categories  ==
 +
''http://example.com/amember/api/product-category?_key=APIKEY
 +
 
 +
== Product to Category Relations ==
 +
''http://example.com/amember/api/product-product-category?_key=APIKEY
 +
 
 +
== Check Access ==
 +
That is a special controller that allows to check user access by username, e-mail address or username-password pair. It ignores described above additional parameters and accepts only parameters described here. This controller always return results in JSON format.
 +
 
 +
Check access by username and password:
 +
<pre>http://example.com/amember/api/check-access/by-login-pass?_key=APIKEY&login=john&pass=1234</pre>
 +
 
 +
Check access by username:
 +
<pre>http://example.com/amember/api/check-access/by-login?_key=APIKEY&login=test</pre>
 +
 
 +
Check access by e-mail address:
 +
<pre>http://example.com/amember/api/check-access/by-email?_key=APIKEY&email=test@example.com</pre>
 +
 
 +
In case of valid request (username/password is correct and user is found) it returns the following response:
 +
<pre>{
 +
  "ok" : true,
 +
  "name" : "Bob Smith",
 +
  "subscriptions" : { 12 : "2012-04-03", 33: "2050-01-01"} // subscription expirations for products #12 and #33
 +
}</pre>
 +
 
 +
In case of request failure, it returns the following response:
 +
<pre>{
 +
  "ok" : false,
 +
  "code" : 1, // from Am_Auth_Result
 +
  "msg" : "Username or password is incorrect" // from Am_Auth_Result class
 +
}</pre>

Latest revision as of 02:32, 16 November 2016

Contents

aMember Pro Web API (REST)

Since 4.2.6 release aMember Pro provides web api based on REST principles. It allows to fetch and submit information about users, products and payments. It is easy to extend and use, and we expect that list of interfaces will be extended soon.

Enabling of REST API

Go to aMember CP -> Setup -> Plugins, and enable "api" module. If your aMember installation has no "api" module available, you can get it for free in the members area

Once the module is enabled, scroll down and find an admin menu item Remote Api Permissions. Click New Record. You will see a form to fill - your comment about the access key, a generated access key itself, and list of checkboxes describing what system calls is available for given access key. Check necessary calls and Save.

Samples

Fetching list of users via Web API

To try it out, open in your browser http://example.com/amember/api/users?_key=APIKEY

You will see first 20 user records in JSON format and total number of users in _total variable

You can pass additional parameters to control output:

_format
Either: json (default), xml or serialize
_count
Number of records per page (default: 20, max: 100)
_page
Page of output (default: 0 - the first page)
_filter[FIELDNAME]
Adds a WHERE condition for FIELDNAME. If search value contains % it is considered as pattern for SQL LIKE expression, else SQL = condition is used. If several filters provided, it will be concatenated in SQL AND expression.
_nested[]
Requests to include nested records into dataset. For example, if you are accessing users database via REST, you can do it like this:
http://example.com/amember/api/users?_key=APIKEY&format=xml&_nested[]=invoices&_nested[]=access
This will include user's invoices and access records into output. List of available nested tables is unique to each record type.

Adding users via Web API

To add a customer via Web API, you have to use HTTP POST method. There is a sample call to add a user to database:

POST /amember/api/users _key=APIKEY&login=apiadded&pass=0000&email=test@example.com&name_f=John&name_l=Smith&_format=xml 

in case of success it will return added user record.

Updating users via Web API

To update a customer via Web API, you have to either use HTTP PUT method, or make POST and pass _method=PUT parameter with your request. There is a sample call to update a user to database:

PUT /amember/api/users/22
_key=APIKEY&name_f=NewName&pass=1111

in case of success it will return updated user record with first name set to "NewName" and the password set to 1111. Other user fields will be kept untouched. The following call gives the same result:

POST /amember/api/users/22
_method=PUT&_key=APIKEY&name_f=NewName&pass=1111

Deleting users via Web API

To remove a customer via Web API, you have to either use HTTP DELETE method, or make POST and pass _method=DELETE parameter with your request. There is a sample call to add a user to database:

DELETE /amember/api/users/22
_key=APIKEY

in case of success it will return deleted user record as look like before deletion.

Complete examples in PHP

http://www.amember.com/docs/REST_API_examples


Available REST Controllers

Users

http://example.com/amember/api/users?_key=APIKEY Nested Controllers:

  • invoices
  • access

Invoices

http://example.com/amember/api/invoices?_key=APIKEY Nested Controllers (all are enabled by default):

  • invoice-items
  • invoice-payments
  • invoice-refunds
  • access

Payments

http://example.com/amember/api/invoice-payments?_key=APIKEY

Refunds

http://example.com/amember/api/invoice-refunds?_key=APIKEY

Products

http://example.com/amember/api/products?_key=APIKEY Nested Controllers:

  • billing-plans

Affiliate Payouts

http://example.com/amember/api/aff-payouts?_key=APIKEY Nested Controllers:

  • aff-payout-details

Affiliate Payout Details

http://example.com/amember/api/aff-payout-details?_key=APIKEY

Product Categories

http://example.com/amember/api/product-category?_key=APIKEY

Product to Category Relations

http://example.com/amember/api/product-product-category?_key=APIKEY

Check Access

That is a special controller that allows to check user access by username, e-mail address or username-password pair. It ignores described above additional parameters and accepts only parameters described here. This controller always return results in JSON format.

Check access by username and password:

http://example.com/amember/api/check-access/by-login-pass?_key=APIKEY&login=john&pass=1234

Check access by username:

http://example.com/amember/api/check-access/by-login?_key=APIKEY&login=test

Check access by e-mail address:

http://example.com/amember/api/check-access/by-email?_key=APIKEY&email=test@example.com

In case of valid request (username/password is correct and user is found) it returns the following response:

{
   "ok" : true,
   "name" : "Bob Smith",
   "subscriptions" : { 12 : "2012-04-03", 33: "2050-01-01"} // subscription expirations for products #12 and #33
}

In case of request failure, it returns the following response:

{
   "ok" : false,
   "code" : 1, // from Am_Auth_Result
   "msg" : "Username or password is incorrect" // from Am_Auth_Result class
}