MACROMEDIA BREEZE-USING THE BREEZE XML WEB SERVICES, Use Manual

Page: 15 / 196

About parameters 15
Calling an action on the server
To call an action on the Breeze server, pass the relevant parameters to the web services servlet at
http://
server_name /api/xml.
In Breeze 4.0, there are two parameters that are required for all actions: the parameter named
action
specifies the name of the action, and the parameter named
accesskey
specifies the
account’s access key. In Breeze 4.1, you do not need to pass the
accesskey
parameter. Passing the
accesskey
parameter in Breeze 4.1 is not harmful, it is ignored.
Most actions also have other parameters. For more information about access keys, see “About
security” on page 17 . For more information about additional parameters for a given action, see
the action’s documentation in Chapter 4, “Action Reference,” on page 37 .
You can send the parameters to the server in either of the following ways:
•
Create a query string—a URL that includes query parameters—and send it to the server as an
HTTP
GET
or
POST
request, with the HTTP content type set to
"application/
x-www-form-urlencoded"
. (In most cases, you don’t need to explicitly set the content type
when you use this approach.)
The URL to use for the query string has the form
http://breeze.example.com/api/
xml?action=
action_name
&accesskey=
access_key
, with the action’s other parameters
appended as additional query parameters separated by ampersands (&).
•
Create an XML object containing the parameter data as
param
tags contained in a
params
tag,
and then send an HTTP
POST
request to the server, with the HTTP content type set to
"text/xml"
.
For example code demonstrating how to call an action, see Chapter 3, “Common Tasks,” on
page 27 .
Note: The example code in this book uses the query parameters approach, both for readability and
because of limitations in using CFML to send XML objects containing parameter data. Macromedia
recommends using the
POST
method when possible; because of the way HTTP implements
GET
and
POST
, using
POST
may provide higher security levels than passing parameters in the query string. For
more information, see “About security” on page 17 .
About parameters
For most actions, you can specify one or more additional parameters. (The
accesskey
and
action
parameters are required. For more information, see “Calling an action on the server”
on page 15 .)
You usually specify parameters as name-value pairs, but the exact process depends on the details of
the language you use to call the action on the Breeze server. For sample code in ColdFusion
Markup Language (CFML), see
Chapter 3, “Common Tasks,” on page 27 .
In the documentation for each action, all listed parameters are required except for those
specifically marked as optional.