Sending requests

When your application sends an API request to the BlackBerry® Administration API, you must specify data objects, or their IDs, as parameters for some of the API methods. To specify the data objects or their IDs, you must first retrieve the data objects in a separate request. For example, to use the deleteUser() method, you specify the user ID of the user object you wish to delete as a parameter. To retrieve the data object that contains the user's data, you can send a request using the findUser() method.

In Microsoft .NET languages, you can specify a single data object that contains all of the data objects as a parameter. In Java®, you can specify data objects as separate parameters.

Validating the SSL certificate in your application

When you open a connection to a BlackBerry® Administration API web service, you should validate the SSL certificate to make sure you have a secure connection. Most development frameworks provide SSL packages to help you retrieve and validate SSL certificates. It is important to know if your BlackBerry Administration Service uses a self-signed certificate or a certificate-authority signed certificate in order to validate the certificate accordingly.

Creating a data object instance

Most data objects in the BlackBerry® Administration API are standard data objects. To use a data object, you can create a new instance of the class. For example, the following code sample creates a standard data object:
User user = new User();
The API reference for the BlackBerry Administration API identifies some data objects as polymorphic data objects. Polymorphic data objects enable the BlackBerry Administration API to dynamically add or remove functionality as you add or remove the BlackBerry® Enterprise Server components. To use a polymorphic data object, you can create an instance of a data type extension that extends the base class. The names of the data type extensions in the BlackBerry Administration API always end with "Type". For example, the following code sample creates an instance of the type extension BASUserSearchCriteriaServiceAttributesType, which extends the base class UserSearchCriteriaServiceAttributes:
UserSearchCriteriaServiceAttribute attributes = new BASUserSearchCriteriaServiceAttributesType();

Polymorphic data objects are required because the BlackBerry Enterprise Server is divided into components that provide different functionalities. Each component manages different types of data and features, and data type extensions are only available if the component that manages the type extension is installed on your organization's BlackBerry Enterprise Server. For example, the BlackBerry Administration Service manages users' display names. You can always search for user accounts based on users' display names because the BlackBerry Administration Service component is installed on all the BlackBerry Enterprise Server environments. However, you can only search for user accounts based on the users' email addresses if you have a BlackBerry Messaging Agent component installed on your BlackBerry Enterprise Server. If you do not have a BlackBerry Messaging Agent component installed, the type extension used to search based on email addresses does not appear in your WSDL definition.

Specifying authentication credentials

Your application can encode requests so that each request automatically adds authentication credentials to the SOAP header. To encode the authentication credentials, you can use the utilws web service to encode the authentication credentials automatically or you can specify the authentication credentials manually.

To encode a string using the utilws web service, use the encodeUsername() method. To encode the credentials manually, create a string that uses the following format:
<usernameLength>,<domainLength>,<authenticatorTypeLength>,<authenticatorIDLength>,<credentialTypeLength>,<organizationIDLength>;<username><domain><authenticatorType><authenticatorID><credentialType><organizationID>. 
After the string is encoded, you can use the encoded credentials and your password to access all protected web services.

For more information about encoding credentials, and for code samples, see the API reference for the BlackBerry® Administration API.

Previous topic: Development basics

Was this information helpful? Send us your comments.