Making your first API call

Adobe Connect Web Services uses a servlet framework to handle XML API requests. In the data flow diagram, the servlet framework is represented by the API component. The API servlet receives XML requests from clients and returns XML responses from the web application server and the database.

A request to the XML API is formatted as an HTTP request URL that the API servlet handles. A request URL has an action name and parameters in name/value pairs, like this: 

https://example.com/api/xml?action=sco-info&sco-id=2006334909

If you have access to a Adobe Connect account in which you can test API calls, you can experiment. In fact, Adobe recommends testing API calls in the browser while you learn the API and write applications.

Before you begin, it’s useful to install a tool that allows you to view HTTP request and response headers in your browser.

Call common-info in a browser

  1. (Optional) Enable a tool for viewing HTTP headers in your browser.

  2. Open a browser and navigate to your Adobe Connect login page.

  3. Without logging in, delete the part of the URL after the domain name and add a call to common-info : 

    https://example.com/api/xml?action=common-info

    The response from common-info gives you information about your session with the server, especially the cookie that identifies your session: 

    <?xml version="1.0" encoding="utf-8" ?>  
<results> 
    <status code="ok" />  
    <common locale="en" time-zone-id="85"> 
        <cookie>breezbryf9ur23mbokzs8</cookie>  
        <date>2008-03-13T01:21:13.190+00:00</date>  
        <host>https://example.com</host>  
        <local-host>abc123def789</local-host>  
        <url>/api/xml?action=common-info</url>  
        <version>connect_700_r641</version>  
        <user-agent> 
            Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;  
            .NET CLR 1.1.4322) 
        </user-agent>  
    </common> 
</results>

    When you log a user in from an application, you need to send the cookie value back to the server to identify the user’s session (see Log in from an application ).

Call principal-list in a browser

Once you have the BREEZESESSION cookie value from common-info , the browser adds it to the request header on your next request.

  1. In a web browser, log in to Adobe Connect. Change the browser URL to call principal-list : 

    https://example.com/api/xml?action=principal-list

  2. Check the request header. This time it sends the BREEZESESSION cookie value back to the server: 

    GET /api/xml?action=principal-list HTTP/1.1 
Accept: */* 
Accept-Language: en-us 
Accept-Encoding: gzip, deflate 
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322) 
Host: example.com 
Connection: Keep-Alive 
Cookie: BREEZESESSION=breezbryf9ur23mbokzs8

  3. Check the response, which lists all principals on the server, each in its own principal element. 

    <?xml version="1.0" encoding="utf-8" ?>  
<results> 
    <status code="ok" />  
    <principal-list> 
        <principal principal-id="624526" account-id="624520" type="user" 
                has-children="false" is-primary="false" is-hidden="false"> 
            <name>joe harrison</name>  
            <login>jharrison@example.com</login>  
            <email>jharrison@example.com</email>  
        </principal> 
        <principal principal-id="624550" account-id="624520" type="user" 
                has-children="false" is-primary="false" is-hidden="false"> 
            <name>bob jones</name>  
            <login>bjones@example.com</login>  
            <email>bjones@example.com</email>  
        </principal> 
        ... 
    </principal-list> 
</results>

Add filters and sorts

Many actions in the API allow you to add a filter to return only certain response elements or a sort to display response elements in a certain order.

A filter is a special parameter that starts with the keyword filter , followed by an optional modifier, then a field name and a value. These are all examples of filters:

  • filter-name=jazz doe (which matches results with the exact name jazz doe )

  • filter-like-name=jazz (which matches any results that contain jazz in the name)

  • filter-out-type=user (which returns any results that do not have a type of user )

These are just a few filter types, and you can find more in filter-definition . Check an action in the reference (at Action reference ) to see whether its response can be filtered. In general, if an action allows filters, you can use them on any response element or attribute.

A sort is another special parameter that starts with the keyword sort (or sort1 or sort2 ), followed by a field name and then one of the keywords asc or desc , for example:

  • sort-name=asc (to sort in ascending order by name )

  • sort-group-id=desc (to sort in descending order by group-id )

These are just a few sort examples. You can test sorts in the browser or see sort-definition for more.

Make a call with a filter and sort

  1. Call principal-list again, displaying only groups and sorting them alphabetically by name: 

    https://example.com/api/xml?action=principal-list&filter-type=group 
    &sort-name=asc

  2. To tighten the response, choose a group from the list and filter on its name: 

    https://example.com/api/xml?action=principal-list&filter-name=developers

    This time, only one group is returned: 

    <?xml version="1.0" encoding="utf-8" ?>  
<results> 
    <status code="ok" />  
    <principal-list> 
        <principal principal-id="2007105030" account-id="624520"  
                    type="group" has-children="true" is-primary="false"  
                    is-hidden="false"> 
            <name>developers</name>  
            <login>developers</login>  
        </principal> 
    </principal-list> 
</results>

Where to go from here

At this point, you can continue to test calls in the browser and observe how they work. It’s the best and easiest way to learn the XML API. When you need more information, turn to any of these sources:

// Ethnio survey code removed