The REST Server API is based on the Atom
Syndication protocol because it uses the Service, Feed, and Entry
objects to structure a hierarchy of resources.
Note:
The
Atom Syndication specification requires Entry to contain an Author
element, a Summary element, and a Title element. The application uses
the Entries that do not contain these elements whenever they are not
appropriate for the resource the Entry represents, and also applicable
for the Atom Feeds, which are required to contain both Author and
Title elements.
The REST Server API also defines other objects to represent all
the resources IBM® Tivoli® Directory
Integrator Server supports. The default
representation of the resources is JSON, but each client application
can use the REST Server to work with XML. This API is configurable
on a per-request level, using the appropriate HTTP headers.
The REST Server API has a single point of Entry, which is represented
by the http://{host}:{port}/rest URL, where:
host - specifies the name or IP address of the
system on which IBM Tivoli Directory
Integrator is running.
port - specifies the port on which the embedded
web container is listening to.
The rest of the resources within the API are opaque. The client
applications use the provided URLs as Atom links within the Atom Entries
to traverse the resources hierarchy and operate on them.
The following diagram depicts the available resources and the links
that the client applications need to follow to navigate the hierarchy.
Note:
Only the important Atom resources are shown
in the diagram.
The URL.method()[qs1, qs2] notation is used to represent
an invocation of the HTTP method on the specified URL with query parameters.
The URL is represented as a set of names separated by a dot. Each
name in that path uses one of the following options to refer to a
resource available, after resolution of all the names preceding it.
For a list of resources (Service Document containing a list of
collections, Atom Feeds containing a list of Atom Entries), the category
of the subresources is used to uniquely identify its type. For example:
To refer to the Server Feed, the Service Document is checked for
a collection with category "server" and specified
as URL: {server}
To refer to an Atom Entry with category "info" in
the Server Feed, the URL: {server}.{info} notation is used.
Atom Entries contain links to other resources. To refer to those
resources, the value of "rel" attribute is used in
the Atom link. For example, to refer to the Component Feed, the URL:
{server}.{info}.component notation is used.
The {server}.{info}.component.{connector}.get() statement
indicates that an HTTP GET request is sent to the URL of the Atom
Entry that represents a Connector Entry resource. See the Example algorithm section for more details.
The Component Feed provides a list of all the IBM Tivoli Directory
Integrator components
such as Connectors, Function Components, and Parsers that are installed
on the server.
The CustomNotification type allows
specification (using the "type" attribute) of the
payload within the "data" element. The following values
are recognized:
text/* - the payload is parsed as a String object.
This value is the default value if the "type" attribute
is missing.
application/octet-stream - a Base64 encoded
byte array, which is decoded and sent as is.
application/octet-stream+object - a Base64 encoded
byte array, which is decoded, de-serialized, and sent as an
object.
The successful response contains no body and no location header.
The HTTP code is 204 (No Content).
The Configuration Feed provides access to the Server API Config
directory containing the deployed IBM Tivoli Directory
Integrator configurations.
The Rest Server API represents a configuration file using an Atom
Entry, but represents a subdirectory as both Atom Entry (in the context
of an Atom Feed) and as Atom Feed (when listing the directory content).
To represent a multi-leveled hierarchy in the defined URL syntax,
the following single level notation is used:
{configuration}.{directory} - this syntax refers to any
Atom Entry representing a directory within the hierarchy (not necessarily
as direct child of the Server API Configs directory).
{configuration}.{directory}.content - this syntax refers
to any Atom Feed representing the content of a directory within the
hierarchy (not necessarily as direct child of the Server API Configs
directory).
{configuration}.{file} - this syntax refers to any Atom
Entry representing a configuration file within the hierarchy (not
necessarily as direct child of the Server API Configs directory).
Creates a configuration file with the provided
configuration data
The path of the configuration file is relative
to the base directory represented by the Atom Feed to which an HTTP
POST request is sent. The path is taken from the name specified in
the CreateConfig object.
On success, the HTTP code 201 is returned
along with a location header pointing to the newly created configuration
file Atom Entry. The response body contains a copy of that Atom Entry.
Obtains an Atom Entry representing a particular
configuration directory. This entry does not show the content of the
directory. To access the content, use the "content" link
to retrieve the Atom Feed representation.
Obtains an Atom Entry representing a particular
configuration file
Operation
{configuration}.{file}.delete()
Details
Deletes the deployed configuration file on the IBM Tivoli Directory
Integrator Server
Configuration File Editing
Client applications can edit a deployed configuration file. To
co-ordinate the multi-client access to the single configuration
file, you need to lock the configuration file. The REST Server API
allows you to obtain a lock of a configuration file (assuming that
file is not already locked), submit multiple changes while holding
the lock of the file, and unlock it for others to use.
Requests a lock on the deployed configuration
file. The configPassword is used only when creating the
lock, and ignored while updating the already locked configuration
file.
On success, the configuration file is locked and an HTTP code
of 201 (Created) is returned. The location header contains a link
to the configuration lock resource and the body contains a representation
of the lock.
If the configuration is already locked, the request
fails with HTTP code 409 (Conflict). The configuration file stays
locked until:
Explicit unlocking is performed using DELETE HTTP operation.
A Server API lock timeout is configured on the IBM Tivoli Directory
Integrator Server
and has expired.
On success, the response body contains the lock
object representation. An error with the following HTTP codes is returned:
404 (Not found) - the lock was released either explicitly
by another administrator user or by the Server API automatic unlocking
function and is not acquired since.
403 (Forbidden) - the lock was previously acquired by another
user.
Updates the lock protecting the configuration.
This request does not release the lock. On success, the response body
contains the updated lock object representation. An error with the
following HTTP codes is returned:
404 (Not found) - the lock was released either explicitly
by another administrator user or by the Server API automatic unlocking
function and is not acquired since.
403 (Forbidden) - the lock was previously acquired by another
user.
Operation
{configuration}.{file}.lock.delete()
Details
Releases the lock
An error with HTTP code
404 (Not found) is returned if the lock was released either explicitly
by another administrator user or by the Server API automatic unlocking
functionality and is not acquired since.
Starts a ConfigInstance on the Server. The StartCI item
allows the configuration to be specified in two ways:
configRef - specifies the Atom Entry ID of the configuration
file.
solution - specifies the configuration data without using
a configuration file.
On success, the HTTP code 201 (Created) is returned along with
a location header pointing to the newly created ConfigInstance Atom
Entry. The response body contains a copy of that Atom Entry.
Obtains an Atom Entry representing a particular
ConfigInstance.
A link is provided to point to the actual configuration
file this ConfigInstance is loaded from. If this ConfigInstance is
temporary, the link is not provided.
Starts an AssemblyLine on the Server. The startAL
object contains the name of the AssemblyLine from the ConfigInstance
configuration
On success, the HTTP code 201 (Created) is returned
along with a location header pointing to the newly created AssemblyLine
Atom Entry. The response body contains a copy of that Atom Entry.
Obtains an Atom Entry representing a particular
AssemblyLine.
A Category with term "active" of
scheme "http://www.ibm.com/xmlns/prod/tdi/rest#assembly-line" specifies
that the AssemblyLine is still active.
A Category with term "manual" of
scheme "http://www.ibm.com/xmlns/prod/tdi/rest#assembly-line" specifies
that the AssemblyLine is started in manual mode. A link with relation handle is
also available.
Obtains the "ALHandle" object
with only thestate attribute and "resultEntry" element
(if available). This object is used to control AssemblyLines in manual
mode.
The "state" attribute has the following possible
values:
init - the AssemblyLine is created
and cycles are yet to be processed.
processing - the AssemblyLine was requested
to make a cycle (using a PUT) and was not completed.
done - the AssemblyLine was requested
to make a cycle which is completed.
closed - the AssemblyLine handle is
already closed.
Manual
AssemblyLines takes a long time to execute a cycle. The API creates
a thread for the client call to return.
Note:
This particular
operation is not idempotent as defined by the HTTP specification.
The result of this method is not always the same.
Successful
response will have HTTP code 200 and contains a snapshot of the ALHandle object.
The ALHanlde object contains the result of AssemblyLine
cycle execution, if it is completed before the call returns. If not,
the ALHandling state is set to processing.
If
you execute this operation while another cycle is still being executed,
an HTTP code 409 (Conflict) is returned and your request is ignored.
Runs a JavaScript in the context of the AssemblyLine.
If the executed script returns a value, the response code is 200 (OK).
Else, the 204 (No Content) code is returned
If the retuned script
value is IBM Tivoli Directory
Integrator Entry, it is retuned as is. Else,
a new IBM Tivoli Directory
Integrator Entry is created and the value is placed
in the "value" attribute.
Creates a PropertyStore for a particular ConfigInstance
On
success, the HTTP code 201 (Created) is returned along with a location
header pointing to the newly created PropertyStore Atom Entry. The
response body contains a copy of that Atom Entry
Obtains an Atom Entry representing a particular PropertyStore
A category with term "default" of scheme "http://www.ibm.com/xmlns/prod/tdi/rest#property-store" specifies
that the PropertyStore is the default entry
A category with term "password" of scheme "http://www.ibm.com/xmlns/prod/tdi/rest#property-store" specifies
that the PropertyStore is the password
A category with term "modified" of scheme "http://www.ibm.com/xmlns/prod/tdi/rest#property-store" specifies
that the PropertyStore is updated but not committed
If a category with term "default" of scheme "http://www.ibm.com/xmlns/prod/tdi/rest#property-store" is
present in the request Atom Entry, the PropertyStore is marked as
default Entry.
If a category with term "password" of scheme "http://www.ibm.com/xmlns/prod/tdi/rest#property-store" is
present in the request Atom Entry, the PropertyStore is marked as
the password.
Note:
If the options are not set, the PropertyStore
flags will not be unset. To unset the default flag to PropertyStore,
set it to another PropertyStore.
Requests an incremental update of the PropertyStore,
by setting the value of one or multiple properties
Note:
Removal
of properties is explicit. The request must specify the property and
its name, with no value to remove it. The API does not remove a property,
which is not present in the request list.
On success,
HTTP code 204 (No Content) is returned with an empty response body.
Sets the value of the property specified by the "name" query
parameter. If not found, a new property is created.
Specifying a Boolean value for the "encrypt" parameter,
switches the property value encryption. Default value is "false".
commit - specifies whether all pending changes must be
committed with this request. The default value is "false".
HTTP code 404 is returned if no name is specified
On success, HTTP code 204 (No Content) is returned with an empty
response body
Obtains the Tombstone Feed listing of all the
ConfigInstance Atom Entries for which either a Tombstone is recorded
or there is a child AssemblyLine with Tombstones recorded
Each Listener contains an object that represents the way the messages
are transported. The types of transportation mechanisms are:
Push Channel
Poll Channel
Push channel
The Push Channel uses the HTTP protocol to deliver messages. To
deliver messages, the Push Channel object, inside the registered Listener,
contains the fields that specify the destination URLs, where messages
are sent. A client starts an HTTP server and registers a Listener,
which has a Push Channel that is configured with the URL pointing
to a place on that HTTP server. On each message, the configured listener
sends an HTTP POST request to the specified location.
If the communication with the main server breaks down due to some
error, the Listener tries to post to the fallback server, if provided.
Push Channel makes it easy to deliver real-time notifications as they
occur.
Listeners having Push Channel will also have an Atom Category with
term "push" and scheme "http://www.ibm.com/xmlns/prod/tdi/rest#listener".
Poll Channel
The Poll Channel mechanism is used to achieve near real-time delivery
of notifications.
The mechanism relies on using JMS server that buffers messages
until the client side requests them. The client registers a new Listener,
which has a Poll Configuration. When the Listener is successfully
registered, the client receives an Atom Link with the relation "poll".
Sending HTTP GET requests on that URL obtains each message.
Clients can use the JMS Server to buffer messages to configure
Push Channel to deliver the messages in bunches. This mechanism reduces
the network traffic and also eases the client/server procession when
the source of events produces lot of events in a short time. For other
event sources that produce fewer events, configure them to return
a single event or a smaller bunch of events with a larger timeout
value. Listeners having Push Channel will also have an Atom Category
with term "poll" and scheme "http://www.ibm.com/xmlns/prod/tdi/rest#listener".
Directory Integrator, Version 7.1.1