Click or drag to resize

NetIQ DRA REST Extensions

About this Help

This help file is automatically generated from the DRA REST service source code. While the documentation is generated in a format that is of most use to C# developers it does contain information related to the REST endpoint URIs, the payload contents for each URI, and the response returned to the client.

Endpoints and URIs

The DRA REST API is implemented by the IDRARestServer interface. To see what endpoints are available see the topic on IDRARestServer Memebers. Each member is the implementation of a REST endpoint that maps to a specific URI template noted in the description. The URI template excludes the protocol, server name, and port. Any segment of the URI enclosed in curly braces is considered a variable and will require an appropriate value to be specified by the client as part of the URI. Null or empty values are not supported for URI segment variables

Examples

The URI template for the ComputerCreate(String, Computer, ConnectionParameters) endpoint is

/dra/domains/{domainFqdn}/computers/post

An example of the actual URI used to create a computer through the DRA REST server would be:

https://houDraRest01:8755/dra/domains/MyDomain.corp/computers/post

This will attempt to connect to a DRA REST service running on houDraRest01 port 8755. Along with the appropriate payload this will instruct DRA to create a computer in the MyDomain.corp domain.

Payloads

You can determine what the payload should contain by looking at the endpoint method's parameter list. Any parameter whose name matches a segment variable should not appear in the payload. Instead this value will be populated from the matching URI segment. All other parameters should appear in the payload. Any extra information that appears in a payload but does not match a paramter is ingored.

Property Names in Payloads are Case Sensitive

Object and property names in the json payload are case sensitive. In the help topic for each object the syntax for a property will be displayed as follows

[DataMemberAttribute(Name = "description")]
public string Description { get; set; }

The name of the property in json must match the Name defined in DataMemberAttribute.

This is also true for properties and objects defined in the endpoint's parameter list. The ComputerCreate(String, Computer, ConnectionParameters) method is defined as

Stream ComputerCreate(
    string domainFqdn,
    Computer computer,
    ConnectionParameters connectionParameters
)

The computer object in the json payload must match the case of the parameter name (and not the type). Therefore it should be named "computer" and not "Computer".

Examples

Creating a Computer

The URI template for the above endpoint is

/dra/domains/{domainFqdn}/computers/post

In this example the expected payload should contain a Computer and a ConnectionParameters object. Since the domainFqdn parameter matches the {domainFqdn} segment in the URI it does not have a corresponding entry in the payload. The following is an example of a valid payload:

{
    "computer": {
        "description": "An employee workstation",
        "distinguishedName": "CN=computer01,OU=Workstations,DC=myDomain,DC=corp"
    },
    "connectionParameters": {
        "userName": "DRAAdmin",
        "password": "abcxyz"
    }
}

Descriptions of the fields that can be specified for Computer and ConnectionParameters are available in those topics.

Responses

Internally the return value type for all endpoints is Stream. From the client perspective all endpoints will return json formatted text. For each endpoint method, the description of the return value will include a link to the class that is serialized to create the response. From that class description you can determine the json contents in the same way you can determine what to pass in a payload.

The ContainerEnum(Computer, Computer, Contact, Contact, Domain, Domain, Group, Group, OU, OU, User, User, EquipmentMailbox, RoomMailbox, DynamicDistributionGroup, DynamicDistributionGroup, Container, Container, BuiltinContainer, BuiltinContainer, PowerFilter, AdditionalAndFilters, AdditionalOrFilters, String, EnumerationOptions, ConnectionParameters) method returns a ManagedObjectListResponse. The json contents of the response map to the properties of ManagedObjectListResponse in the same way the json contents of a request payload are mapped to the endpoints parameters. The response will contain json elements for each of the properties of the ManagedObjectListResponse that has a value. The property name used in json is indicaated by the Name defined in the DataMemberAttribute of the property

The following is an example of the json that can be returned from ContainerEnum(Computer, Computer, Contact, Contact, Domain, Domain, Group, Group, OU, OU, User, User, EquipmentMailbox, RoomMailbox, DynamicDistributionGroup, DynamicDistributionGroup, Container, Container, BuiltinContainer, BuiltinContainer, PowerFilter, AdditionalAndFilters, AdditionalOrFilters, String, EnumerationOptions, ConnectionParameters)

{
    "computers": [],
    "contacts": [],
    "domains": [],
    "groups": [],
    "dynamicDistributionGroups": [],
    "ous": [],
    "users": [
        {
            "class": "User",
            "distinguishedName": "CN=Administrator,CN=Users,DC=myDomain,DC=corp",
            "friendlyName": "Administrator",
            "friendlyPath": "myDomain.corp/Users/Administrator",
            "friendlyParentPath": "myDomain.corp/Users",
            "name": "Administrator",
            "objectClass": "User",
            "path": "OnePoint://CN=Administrator,CN=Users,DC=myDomain,DC=corp"
        },
        {
            "class": "User",
            "distinguishedName": "CN=Guest,CN=Users,DC=myDomain,DC=corp",
            "friendlyName": "Guest",
            "friendlyPath": "myDomain.corp/Users/Guest",
            "friendlyParentPath": "myDomain.corp/Users",
            "name": "Guest",
            "objectClass": "User",
            "path": "OnePoint://CN=Guest,CN=Users,DC=myDomain,DC=corp"
        },
        {
            "class": "User",
            "distinguishedName": "CN=krbtgt,CN=Users,DC=myDomain,DC=corp",
            "friendlyName": "krbtgt",
            "friendlyPath": "myDomain.corp/Users/krbtgt",
            "friendlyParentPath": "myDomain.corp/Users",
            "name": "krbtgt",
            "objectClass": "User",
            "path": "OnePoint://CN=krbtgt,CN=Users,DC=myDomain,DC=corp"
        }
    ],
    "equipmentMailboxes": [],
    "roomMailboxes": [],
    "containers": [],
    "builtinContainers": [],
    "resumeString": "",
    "totalNumberOfObjects": 3,
    "numberOfRowsReturned": 3,
    "isSearchFinished": true,
    "draServerAndPort": "DraServer01:11192",
    "errors": []
}
Namespaces
NamespaceDescription
NetIQ.DRA.Common.Rest.DataModels
NetIQ.DRA.Common.Rest.Requests
NetIQ.DRA.Common.Rest.Responses
NetIQ.DRA.Common.Rest.Web
NetIQ.DRA.RestServiceLibrary

Namespace for defining the REST interfaces and the classes to process REST requests sent to the DRA Host service.

The IDRARestServer interface defines the access for REST endpoints. See the documentation for a specific interface for information about how to call the interface.