Example Request - iModules Client Community

advertisement

Web Services 101
James Payne
Managing Director for New Media / Advancement
July 30, 2013
Agenda
 Introductions
 Web Services Overview
 Definition
 Examples of web services
 iModules Web Services
 Technologies
 Using
What is a web service?
- Also known as ‘APIs’
- A building block for ‘Service-Oriented
Architecture’ (SOA)
- Used to tie systems together
- Used to provide access by a provider to
services or data to a consumer other than
a browser… But sometimes to a browser
(AJAX)
What are some examples of web services?
Companies
- Google
- Facebook
- Twitter
- Yelp!
- LinkedIn
- Everyone
What are they used for?
Example: Real Estate Web Site
- IP location lookups (Various)
- Real estate listings (MLS)
- Secondary School Details (education.com)
- Business Reviews (Yelp!)
- Job Listings (simplyhired.com)
- Census Data (www.census.gov)
- Custom Mapping (Google)
- Advertising details for integrated
marketing (Various)
What can I do with iModules web services?
There are actually seven web services…
GeneralQuery.asmx
Provides access to non-instance fields
that are not specific to any Form
ControlQuery.asmx
Provides access to fields that are specific to a
form
TransactionsQuery.asmx
Instance fields that are specific to a
commerce transaction
EmailCategoryQuery.asmx
Allows the import and export of Email
Category opt-out information
LoginQuery.asmx
Allows logging a constituent in by proxy
MemberMergeQuery.asmx
Allows queuing a non-member record and an
associated constituent record for the nightly
Member Merge process
ContentQuery.asmx
Allows pulling event listing / calendars, and
event content information
What technologies do I need to know?
- XML
- HTTP
- Some Programming Language
HTTP (1/3)
- A request/response protocol for data communications between
computers
- Resources are specified with a URL – Uniform Resource Locator
- A number of request types (or methods) are supported; GET,
POST, PUT, DELETE, others
- A request returns a status and possibly some additional
diagnostic or application data
- 200 – Success
- 401 – Unauthorized (*)
- 404 – Not Found
- 400 – Bad Request
- 418 – I’m a teapot (IETF RFC 2324)
HTTP (2/3) Client Request
- The first line of an HTTP request consists of a method, a resource
specification, and an optional version number.
- A number of header lines (key/value pairs) may follow.
- Depending on the method, a content body may be attached.
GET /index.html HTTP/1.1
Host: www.example.com
Source: Wikipedia
HTTP (3/3) Server Response
HTTP/1.1 200 OK
Date: Mon, 23 May 2005 22:38:34 GMT
Server: Apache/1.3.3.7 (Unix) (Red-Hat/Linux)
Content-Type: text/html; charset=UTF-8
Content-Length: 131
Connection: close
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;An Example Page&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
Hello World, this is a very simple HTML document.
&lt;/body&gt;
&lt;/html&gt;
Source: Wikipedia
XML
- XML is a markup language designed to facilitate transportation
and storage of data in a human readable format.
- XML has similarities to HTML but is different; HTML is designed
to display data
Simple Example:
&lt;note&gt;
&lt;to&gt;Tove&lt;/to&gt;
&lt;from&gt;Jani&lt;/from&gt;
&lt;heading&gt;Reminder&lt;/heading&gt;
&lt;body&gt;Don't forget me this weekend!&lt;/body&gt;
&lt;/note&gt;
Source: http://www.w3schools.com/xml/note.xml
Some Programming Language
The language used must…
- Support string handling and concatenation
- Support HTTP network interaction
- Support some sort of data input and output
That’s just about every language…
- Perl, Java, VB, VBScript, C#, Python
Other Buzzwords/Acronyms You’ll Hear…
JSON
JavaScript Object Notation
REST
Representational State Transfer
SOAP
Simple Object Access Protocol
WSDL
Web Service Definition Language
How do I use them?
-
Documentation
Access
Options for Calling Web Services
Crafting the URL
Using the Web Service Help Pages
Creating the request
Placing the request
Consuming the response
Documentation
- iModules has very good web service
documentation
- Download it at…
https://confluence.imodules.com/display/help/
iModules+Web+Services+2.1+-+Engineering
+Documentation
- Or just search the Internet for
imodules web service 2.1
Access
- You will need a username and
password to access web services
- Tell your account manager that you
would like to use web services
- Your account manager will arrange
access for you
Options for Calling the Web Services
There are several ways of calling the web
services from your program…
- SOAP 1.1 or 1.2
- HTTP GET
- HTTP POST
Crafting the URL
Base URL (USA)…
https://api.imodules.com/ws/21/
Web Service…
GeneralQuery.asmx
Operation…
GetAllColumns
For SOAP or WSDL…
https://api.imodules.com/ws/21/GeneralQuery.asmx
For HTTP get…
https://api.imodules.com/ws/21/GeneralQuery.asmx/GetAllColumns?
login=string&amp;password=string
For HTTP post…
https://api.imodules.com/ws/21/GeneralQuery.asmx/GetAllColumns
Using the Web Service Help Pages (/2)
The Web Service Definition Language pages can be used to experiment with web
service requests and responses.
Using the Web Service Help Pages (2/2)
Creating a Request (SOAP)
Example Request…
&lt;soapenv:Envelope
xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;
xmlns:con=&quot;http://imodules.com/WebServices/ControlQuery/&quot;&gt;
&lt;soapenv:Header/&gt;
&lt;soapenv:Body&gt;
&lt;con:GetAllColumns&gt;
&lt;con:login&gt;A309979A-AFB2-4C49-BBB7-4086B5134755
&lt;/con:login&gt;
&lt;con:password&gt;supersecret&lt;/con:password&gt;
&lt;con:controlId&gt;896&lt;/con:controlId&gt;
&lt;/con:GetAllColumns&gt;
&lt;/soapenv:Body&gt;
&lt;/soapenv:Envelope&gt;
Creating a Request (HTTP GET)
GET /ws/21/GeneralQuery.asmx/GetAllColumns?login=A309979A-AFB2-4C49-BBB74086B5134755&amp;password=supersecret&amp;controlId=896 HTTP/1.1
Host: api.imodules.com
You can do a GET from the browser…
Creating a Request (HTTP POST)
POST /ws/21/GeneralQuery.asmx/GetAllColumns HTTP/1.1
Host: api.imodules.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 64
login=A309979A-AFB2-4C49-BBB7-4086B5134755
&amp;password=supersecret&amp;controlId=896
Note: The SOAP method on a previous slide also utilizes a POST operation.
Placing the Request (1/2)
1) Create the request payload
2) Create an HTTP request using your language’s native
functionality
- Specify URL and HTTP method (GET or POST)
3) Set content_type and content_length for POST and SOAP
- Content type is application/x-www-form-urlencoded or
text/xml
- Content length is based on the request body size character
count
4) Send the request
5) Read the response
6) Check the status; if it’s 200, the request succeeded(*). Parse the
returned XML and continue
7) If the status is not 200, an error has occurred. Handle the error.
Placing the Request (2/2)
Note: If the username or password is wrong, the iModules web
service call will return 200/OK instead of 401/Unauthorized. The
return content body will indicate that the credentials are wrong.
Consuming the Response
Stitch Together Calls to Get the Results You Want
For example, to get all instance and non-instance fields for gift records…
GetTransactionsAllSince
https://api.imodules.com/ws/21/TransactionsQuery.asmx
Loop…
Filter based on control IDs for gift forms
GetAllColumns for a control to use to pass to the next control-oriented
service call
https://api.imodules.com/ws/21/ControlQuery.asmx
GetOneMemberByMemberId including member ID, control ID, and columns
https://api.imodules.com/ws/21/ControlQuery.asmx
End loop
Resources
iModules Web Service v2.1 Documentation
https://confluence.imodules.com/display/help/iModules+Web+Services+2.1+
-+Engineering+Documentation
XML
http://www.w3schools.com/xml/
HTTP
http://www.jmarshall.com/easy/http/
SoapUI
http://sourceforge.net/projects/soapui/files/latest/download
XML Pretty Print
http://xmlprettyprint.com/
Web Services 101
James Payne
[email protected]
Questions?