Web Services 101

joeneetscompetitiveΑσφάλεια

3 Νοε 2013 (πριν από 3 χρόνια και 9 μήνες)

86 εμφανίσεις


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 (
e
ducation.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


GET /
index.html

HTTP/1.1

Host:
www.example.com


Source: Wikipedia

-
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.

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


<html>


<
head>



<
title>An Example Page</title>


<
/head>


<
body>



Hello
World, this is a very simple HTML document.


<
/body
>

<
/html
>



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:


<note>


<
to>
Tove
</to>


<
from>
Jani
</from>


<
heading>Reminder</heading>


<
body>Don't forget me this weekend!</body>

</note
>


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

i
modules

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&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…



<
soapenv:Envelope




xmlns:soapenv
="http://
schemas.xmlsoap.org
/soap/envelope/"


xmlns:con
="http://
imodules.com
/
WebServices
/
ControlQuery
/">


<
soapenv:Header
/>


<
soapenv:Body
>


<
con:GetAllColumns
>


<
con:login
>
A309979A
-
AFB2
-
4C49
-
BBB7
-
4086B5134755



<
/
con:login
>


<
con:password
>
supersecret
<
/
con:password
>


<
con:controlId
>
896
</
con:controlId
>


</
con:GetAllColumns
>


</
soapenv:Body
>


</
soapenv:Envelope
>

Creating a Request (HTTP GET)


GET
/
ws
/21/
GeneralQuery.asmx
/
GetAllColumns?login
=
A309979A
-
AFB2
-
4C49
-
BBB7
-
4086B5134755
&password=
supersecret
&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
&
password
=
supersecret
&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
T
ogether 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

j
ames.payne@dartmouth.edu


Questions?