MACROMEDIA BREEZE 5, Руководство по интеграции

Страница: 16 / 232

16 Chapter 1: Using the Breeze XML APIs
Note: The example code in this book uses the query parameters approach, both for readability and
because of limitations in using Macromedia ColdFusion Markup Language (CFML) to send XML
objects containing parameter data. Macromedia recommends using the
POST
method when possible.
Because of the way that 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 18 .
Logging in to Breeze first
To call most APIs, you must be acting as a particular logged-in user, so you must call the
login
API before you can call most other APIs. (You can call the following APIs without logging in:
action-list
,
common-info
,
login
, and
user-accounts
.)
When you log in, the Breeze server returns XML results, which indicate a successful login. The
HTTP headers of those results include a cookie called
BREEZESESSION
. When you receive the
results of a
login
call, save the value of that cookie. You must include the value of the
BREEZESESSION
cookie in every subsequent request that you make as that logged-in user; if you
don’t supply the cookie, the API fails. For examples of how to do this, see “Logging in to Breeze”
on page 29 .
Your application can log in multiple users and can call APIs for any of those users. For example,
when an ordinary user is using your application, you may want to authenticate as that user and
call APIs using that user’s credentials, while also keeping an administrative user logged in to
perform tasks that require higher levels of permissions.
For more information about security in Breeze, see “About security” on page 18 .
About parameters
For most APIs, you can specify one or more additional parameters. (The
action
parameter is
required. For more information, see “Calling an API 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 API 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 API, all listed parameters are required except for those that are
specifically marked as optional.
For some APIs, you can provide multiple parameters with the same name. For example, the
principals-delete
API takes a parameter named
principal-id
; you can specify multiple
principal-id
name-value pairs (each with the name
principal-id
) when you call the API on
the Breeze server.
The following CFML code example shows how to delete two specified users in a single API call,
by specifying two
principal-id
parameters. (This example relies on variables called
baseurl
and
loginCookie
, which you would set during the login process. For more information, see
“Integrating Breeze with a directory service” on page 33 .)
<cfset idOne=12345>
<cfset idTwo=23456>
<cfhttp url="#baseurl#api/xml?action=principals-delete&principal-
id=#idOne#&principal-id=#idTwo#" method="post">