User Guide
Calling an API on the server 15
4.
As part of executing the code, the application server calls an API on the company’s Breeze server,
requesting the list of courses. The API call takes the form of an HTTP
POST request.
5.
The Breeze server executes the API, returning the resulting XML data to the application server.
6.
The application server code parses the returned XML, inserts data into the web page as
appropriate, and then passes the finished page to the web server.
7.
The web server passes the finished page to the browser to be displayed.
Calling an API on the server
To call an API on the Breeze server, pass the relevant parameters to the web services servlet at
http://server_name/api/xml. To call the Breeze XML APIs, you can use any language that can use
XML over HTTP.
There is one parameter that is required for all APIs: the parameter named
action, which specifies
the name of the API. You append the
action parameter to the web services servlet URL with a
query string, as follows:
http://server_name/api/xml?action=action_name
Most APIs also have other parameters. For more information about additional parameters for a
given API, see the documentation for that API in Chapter 4, “XML API Reference,” on page 41.
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
. (When you use this approach, in most cases you don’t need to
explicitly set the content type.)
The URL to use for the query string has the form
http://breeze.example.com/api/
xml?action=action_name
, with the parameters of the API 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
or application/xml.
The following code calls the
login API using a GET HTTP request:
http://admin.breezecentral.com/api/
xml?action=login&login=jon@doe.com&password=foobar
The following is the equivalent call using POST instead of GET:
<params>
<param name="action">login</param>
<param name="login">jon@doe.com</param>
<param name="password">foobar</param>
</params>
For example code demonstrating how to call an API, see Chapter 3, “Common Tasks,” on
page 27.