I4A API Guide: Difference between revisions

From i4a API Wiki
Jump to navigation Jump to search
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= I4A API Guide =
= I4A API Guide =
<blockquote style="border: solid red; width: 75%; padding: 10px">
<font color="#bf110b"><big>'''Update your API integrations to v 2.0 before March 31, 2024.'''</strong></big></font>
Version 2.0 of our API offers more security and is easier to implement and use. It offers numerous endpoints for retrieving data - such as Contacts, Membership, and custom views.
API v 1.0 will continue to work until '''March 31, 2024'''. We encourage you or your third-party vendors to update your integrations now.
[https://api.i4a.com/index.php/I4A_API_2.0 i4a API 2.0 documentation]
</blockquote>


== About ==
== About ==


This guide will outline how to use the Internet4associations API.  The api makes use of the SOAP protocol for authentication only.  All other aspects of the API use REST.
This guide will outline how to use the Internet4associations REST API.


Currently the API determines if the user wishes to retrieve an Object or a Collection based on the plurality of the object. So requesting: /membership.contact/ and /membership.contacts/ will access the object and the collection respectively.   There is also a /view.XXX/ method that will allow you to retrieve a table or view directly, however that mode is and always will be READONLY.
Currently the API determines if the user wishes to retrieve an Object or a Collection based on the plurality of the object. So requesting: /membership.contact/ and /membership.contacts/ will access the object and the collection respectively. There is also a /view.XXX/ method that will allow you to retrieve a table or view directly, however that mode is and always will be READONLY.


==  Security ==
==  Security ==
Line 11: Line 22:
Information is available on the [[API Settings]] page on how to obtain the values needed to authenticate and update them if need be.
Information is available on the [[API Settings]] page on how to obtain the values needed to authenticate and update them if need be.


Authentication can come in one of 2 forms:
=== REST Authentication ===
=== REST Authentication ===
REST is the preferred method of authenticating with your API.
REST is the preferred method of authenticating with your API.
To authenticate with REST you would simply navigate to:
To authenticate with REST you would simply navigate to:
* <pre>http://<site.com>/i4a/api/authenticate/<USER>/<PASSWORD>/<TOKEN></pre>
* <pre>https://<yourwebsite.com>/i4a/api/authenticate/<USER>/<PASSWORD>/<TOKEN></pre>
 
You will get back a json packet which will contain your authKey which you can then use to make calls to the API.


You will get back a JSON packet which will contain your '''authKey''' which you can then use to make calls to the API.
<!--
=== Soap Authentication ===
=== Soap Authentication ===
This method is deprecated and should no longer be used for new projects.
'''This method is deprecated and should no longer be used for new projects.'''
* Use the SOAP method authenticateAdmin that is available from the SOAP WSDL located at:  
* Use the SOAP method authenticateAdmin that is available from the SOAP WSDL located at:  
** <pre>http://<site.com>/i4a/utilities/authenticate.cfc?wsdl</pre>
** <pre>https://<yoursite.com>/i4a/utilities/authenticate.cfc?wsdl</pre>


The authenticateAdmin takes 3 parameters, they are:
The authenticateAdmin takes 3 parameters, they are:
Line 28: Line 38:
*  Password: the password for the user.
*  Password: the password for the user.
*  Token: The Token is specific to each website.  It will be made available in your site admin.
*  Token: The Token is specific to each website.  It will be made available in your site admin.
 
-->


== Syntax ==
== Syntax ==
Calling the API involves building a URL that the API engine can decode. The API engine uses the REST method. REST allows you to utilize GET, POST and DELETE methods. Currently the i4a api only supports GET, which means the API is read-only at this time.
Calling the API involves building a URL that the API engine can decode. The API engine uses the REST method. REST allows you to utilize GET, POST and DELETE methods. Currently the i4a API only supports GET, which means the API is '''read-only''' at this time.


To access the API you can test it in your browser. First you should login to your admin, then direct your page to:
To access the API you can test it in your browser. First you should login to your admin, then direct your page to:


<pre>http://site.com/i4a/api/json/membership.contact/24228/<authkey></pre>
<pre>https://<yourwebsite.com>/i4a/api/json/membership.contact/24228/<authkey></pre>


Another method could be:
Another method could be:


<pre>http://site.com/i4a/api/json/membership.contacts/city like Chicago/<authkey></pre>
<pre>https://<yourwebsite.com>/i4a/api/json/membership.contacts/firstName like Rob/<authkey></pre>


The REST command is broken up into several parts, they are from left-right
The REST command is broken up into several parts, they are from left-right:


* <code>http://site.com/i4a/api/</code> - this is the base url that every api call will have in common
* <nowiki>https://<yourwebsite.com>/i4a/api/</nowiki> - this is the base URL that every API call will have in common.
* /json/ This tells the processor what format to return data in. The options here are Json, XML and WDDX. Json is the fastest format and also more common when using AJAX. For more information see [[api_return_format|API Return Format]]
* /json/ - this tells the processor what format to return data in. The options here are JSON, XML and WDDX. JSON is the fastest format and also more common when using AJAX. For more information see [[api_return_format|API Return Format]]
* /membership.contact/ - This tells the processor what object or table to access.   
* /membership.contact/ - this tells the processor what object or table to access.   
* /city like Chicago/ - This allows you to filter your results.
* /city like Chicago/ - this allows you to filter your results.


=== Filtering ===
=== Filtering ===
Some examples:
Some examples:


* /firstname=don/ - returns records that match firstname=don
* /firstname=john/ - returns records that match firstname=john
* /City Like Chicago/ - returns records where the city field starts with Chicago
* /City Like Chicago/ - returns records where the city field starts with Chicago
* /City CONTAINS CAN/ - finds records where the city field contains the string 'CAN'
* /City CONTAINS CAN/ - finds records where the city field contains the string 'CAN'
* /logincount > 500 / (Need to test this
* /logincount > 500 / (Need to test this
* /NULL/ - For querying a collection of records, this would allow for NO filter. This is required because simply leaving the filter empty results in 2 // and the 2nd / is removed by apache during the processing.
* /NULL/ - For querying a collection of records, this would allow for NO filter. This is required because simply leaving the filter empty results in 2 // and the 2nd / is removed by apache during the processing.


== API Objects ==
== API Objects ==
Line 62: Line 72:
== API Examples ==
== API Examples ==


* /i4a/api/json/membership.contact/24228/<authkey> - Returns a json packet for contact record ID = 24228
* /i4a/api/json/membership.contact/24228/<authkey> - Returns a JSON packet for contact record ID = 24228
* /i4a/api/xml/membership.contact/24228/<authkey> - returns an xml packet for contact record ID = 24228
* /i4a/api/xml/membership.contact/24228/<authkey> - returns an XML packet for contact record ID = 24228
* /i4a/api/wddx/membership.contact/24228/<authkey> - Returns a WDDX packet for contct record ID = 24228
* /i4a/api/wddx/membership.contact/24228/<authkey> - Returns a WDDX packet for contct record ID = 24228
The above examples are only relevent when referencing I4a objects. When interacting with views as below, you must always specify the name/value pair.
The above examples are only relevant when referencing i4a objects. When interacting with views as below, you must always specify the name/value pair.


* /i4a/api/json/view.ams_contactinformation/id=24228/<authkey> - Returns a json packet for contact record ID = 24228
* /i4a/api/json/view.ams_contactinformation/id=24228/<authkey> - Returns a JSON packet for contact record ID = 24228
* /i4a/api/json/view.ams_contactinformation/lastname like L/<authkey> - Returns a json packet that would contain all matching records where lastname started with the letter L
* /i4a/api/json/view.ams_contactinformation/lastname like L/<authkey> - Returns a JSON packet that would contain all matching records where lastname started with the letter L
* /i4a/api/json/view.ams_contactinformation/lastname Like L:isActive=1/<authkey> - Same as above, but further filters by isActive = 1
* /i4a/api/json/view.ams_contactinformation/lastname Like L:isActive=1/<authkey> - Same as above, but further filters by isActive = 1
* /i4a/api/json/membership.contacts/<authkey> - returns all records from the table related to the ORM object com.om.collections.membership.contacts.
* /i4a/api/json/membership.contacts/<authkey> - returns all records from the table related to the ORM object com.om.collections.membership.contacts.
* /i4a/api/json/view.ams_contact/<authkey> - returns the same recordset as the example above, but interacts directly with the table itself.
* /i4a/api/json/view.ams_contact/<authkey> - returns the same recordset as the example above, but interacts directly with the table itself.


[[Additional Examples]]
'''[[Additional Examples]]'''


[[Category:api]]


== Implemention Examples ==
== Implemention Examples ==
* [[i4a api ColdFusion Example|ColdFusion Example]]
* [[i4a api ColdFusion Example|ColdFusion Example]]
* [[i4a api PHP Example|PHP Example]]
* [[i4a api PHP Example|PHP Example]]
* [[i4a api Ajax Example|AJax Example]]
<!-- * [[i4a api Ajax Example|AJAX Example]] -->


== Testing the API ==
== Testing the API ==
Testing the API and inspecting the data returned is very easily achieved with any modern browser.  It is worth noting that by default, only Firefox will display XML (if the header is set to text/xml) in a readable format.  It is possible however in both Google Chrome and Safari to view the xml data in a user-friendly format by going into the developer tools for the browsers. For a better experience however it is recommended you install the following add-ons to each browser for a better experience:
Testing the API and inspecting the data returned is very easily achieved with any modern browser.  It is worth noting that by default, only Firefox will display XML (if the header is set to text/xml) in a readable format.  It is possible however in both Google Chrome and Safari to view the XML data in a user-friendly format by going into the developer tools for the browsers. For a better experience however it is recommended you install the following add-ons to each browser for a better experience:


=== Google Chrome ===
=== Google Chrome ===
* https://chrome.google.com/extensions/detail/mfnjijpckfecpgchobgcfndicenjldoe - will display json data in a user-friendly format. Note: This is a great extension and displays json in a very good format, but it appears when viewing XML with the plugin below this plugin seems to insert some data at the top of the page. The xml viewer still works fine and rest assured this information is not IN the XML packet, but rather added in after by your browser and this plugin.
* https://chrome.google.com/extensions/detail/mfnjijpckfecpgchobgcfndicenjldoe - will display JSON data in a user-friendly format. Note: This is a great extension and displays json in a very good format, but it appears when viewing XML with the plugin below this plugin seems to insert some data at the top of the page. The XML viewer still works fine and rest assured this information is not IN the XML packet, but rather added in after by your browser and this plugin.
* https://chrome.google.com/extensions/detail/gbammbheopgpmaagmckhpjbfgdfkpadb - will display XML and WDDX in a friendly format directly in your browser page.
* https://chrome.google.com/extensions/detail/gbammbheopgpmaagmckhpjbfgdfkpadb - will display XML and WDDX in a friendly format directly in your browser page.


=== Firefox ===
=== Firefox ===
* https://addons.mozilla.org/en-US/firefox/addon/10869 - will display json data in a user-friendly format
* https://addons.mozilla.org/en-US/firefox/addon/10869 - will display JSON data in a user-friendly format


=== Safari ===
=== Safari ===
At this time there appears to be no plugins for Safari that can aid in viewing the data formats, it's recommended you use either Chrome or Firefox if you are going to be interacting with the API from the browser.
At this time there appears to be no plugins for Safari that can aid in viewing the data formats; it's recommended you use either Chrome or Firefox if you are going to be interacting with the API from the browser.


== Links ==
== Links ==
Line 99: Line 108:
* http://en.wikipedia.org/wiki/SOAP - Wikipedia Article on SOAP protocol
* http://en.wikipedia.org/wiki/SOAP - Wikipedia Article on SOAP protocol


[[Category:api]]
[[Category:API]]

Latest revision as of 12:58, 3 November 2023

I4A API Guide

Update your API integrations to v 2.0 before March 31, 2024.

Version 2.0 of our API offers more security and is easier to implement and use. It offers numerous endpoints for retrieving data - such as Contacts, Membership, and custom views.

API v 1.0 will continue to work until March 31, 2024. We encourage you or your third-party vendors to update your integrations now.

i4a API 2.0 documentation

About

This guide will outline how to use the Internet4associations REST API.

Currently the API determines if the user wishes to retrieve an Object or a Collection based on the plurality of the object. So requesting: /membership.contact/ and /membership.contacts/ will access the object and the collection respectively. There is also a /view.XXX/ method that will allow you to retrieve a table or view directly, however that mode is and always will be READONLY.

Security

To access any of the API functionality, you must first authenticate. Information is available on the API Settings page on how to obtain the values needed to authenticate and update them if need be.

REST Authentication

REST is the preferred method of authenticating with your API. To authenticate with REST you would simply navigate to: 

  • https://<yourwebsite.com>/i4a/api/authenticate/<USER>/<PASSWORD>/<TOKEN>

You will get back a JSON packet which will contain your authKey which you can then use to make calls to the API.

Syntax

Calling the API involves building a URL that the API engine can decode. The API engine uses the REST method. REST allows you to utilize GET, POST and DELETE methods. Currently the i4a API only supports GET, which means the API is read-only at this time.

To access the API you can test it in your browser. First you should login to your admin, then direct your page to: 

https://<yourwebsite.com>/i4a/api/json/membership.contact/24228/<authkey>

Another method could be: 

https://<yourwebsite.com>/i4a/api/json/membership.contacts/firstName like Rob/<authkey>

The REST command is broken up into several parts, they are from left-right:

  • https://<yourwebsite.com>/i4a/api/ - this is the base URL that every API call will have in common.
  • /json/ - this tells the processor what format to return data in. The options here are JSON, XML and WDDX. JSON is the fastest format and also more common when using AJAX. For more information see API Return Format
  • /membership.contact/ - this tells the processor what object or table to access.
  • /city like Chicago/ - this allows you to filter your results.

Filtering

Some examples:

  • /firstname=john/ - returns records that match firstname=john
  • /City Like Chicago/ - returns records where the city field starts with Chicago
  • /City CONTAINS CAN/ - finds records where the city field contains the string 'CAN'
  • /logincount > 500 / (Need to test this
  • /NULL/ - For querying a collection of records, this would allow for NO filter. This is required because simply leaving the filter empty results in 2 // and the 2nd / is removed by apache during the processing.

API Objects

API Examples

  • /i4a/api/json/membership.contact/24228/<authkey> - Returns a JSON packet for contact record ID = 24228
  • /i4a/api/xml/membership.contact/24228/<authkey> - returns an XML packet for contact record ID = 24228
  • /i4a/api/wddx/membership.contact/24228/<authkey> - Returns a WDDX packet for contct record ID = 24228

The above examples are only relevant when referencing i4a objects. When interacting with views as below, you must always specify the name/value pair.

  • /i4a/api/json/view.ams_contactinformation/id=24228/<authkey> - Returns a JSON packet for contact record ID = 24228
  • /i4a/api/json/view.ams_contactinformation/lastname like L/<authkey> - Returns a JSON packet that would contain all matching records where lastname started with the letter L
  • /i4a/api/json/view.ams_contactinformation/lastname Like L:isActive=1/<authkey> - Same as above, but further filters by isActive = 1
  • /i4a/api/json/membership.contacts/<authkey> - returns all records from the table related to the ORM object com.om.collections.membership.contacts.
  • /i4a/api/json/view.ams_contact/<authkey> - returns the same recordset as the example above, but interacts directly with the table itself.

Additional Examples


Implemention Examples

Testing the API

Testing the API and inspecting the data returned is very easily achieved with any modern browser. It is worth noting that by default, only Firefox will display XML (if the header is set to text/xml) in a readable format. It is possible however in both Google Chrome and Safari to view the XML data in a user-friendly format by going into the developer tools for the browsers. For a better experience however it is recommended you install the following add-ons to each browser for a better experience:

Google Chrome

Firefox

Safari

At this time there appears to be no plugins for Safari that can aid in viewing the data formats; it's recommended you use either Chrome or Firefox if you are going to be interacting with the API from the browser.

Links

Retrieved from "https://api.i4a.com/index.php?title=I4A_API_Guide&oldid=212"