REST HTTP Methods

This article contains the following topics:
casm1401
This article contains the following topics:
The REST API supports the following HTTP methods to manipulate resources:
  • POST (CREATE) creates a resource.
  • GET (READ) returns a representation of a resource.
  • PUT (UPDATE) updates an existing resource.
  • DELETE deletes the resource.
Refer to this basic set of methods as CRUD. Each method works in the same manner on all CA SDM resources. You require an HTTP client library, available with most programming languages. Use the HTML client library to complete the following tasks:
  • Access and modify associated (or related) resources using a multilevel URI path.
  • Send an HTTP request to the server for the resource that you want to manipulate.
  • Control the object attributes to be returned by using HTTP headers.
After you update Majic object definitions and recycle CA SDM, the product automatically regenerates and redeploys the corresponding Plain Old Java Objects (POJOs) into the REST Tomcat
webapps
directory.
The pdm_rest_util command line utility lets you
manually
generate, compile, and deploy Java code that REST web services require.
Requests for attributes that do
not
respond indicate a null attribute value. Modify your client code accordingly because REST does
not
display null attribute values in responses.
REST Web Services provide a scalable configuration and better flexibility to our users by letting you connect to a dedicated domsrvr on the local server. By default, CA SDM Release 12.9 provides the NX_REST_WEBSERVICE_DOMSRVR variable to domsrvr. You can edit NX.env to change this setting.
CA SDM disables the REST sample mobile user interface and exposes all Majic factories through REST Web Services by default.
The REST API does not support Majic attributes of type DOUBLE.
The following table shows how the REST API uses HTTP methods on resources.
Resource
CREATE
READ
UPDATE
DELETE
Collection URL
For example: http://mywebsite.com/resources/
Creates an entry in the collection. Assigns a new entry URL automatically and returns it by the operation.
Lists the URLs and other details of the collection members.
N/A
N/A
Element URL
For example: http://mywebsite.com/resources/item1
N/A
Retrieves a representation of the addressed member of the collection.
Updates the addressed member of the collection, and when the member does not exist, creates it.
Deletes the addressed member of the collection.
Sample URI Paths for CRUD Operations
The following table shows sample URI paths for CRUD operations:
CRUD Operation
HTTP Method
Noun
Sample URI Path
CREATE
Post
URI
/caisd-rest/chg
READ (Multiple)
GET
Collection URI
/caisd-rest/chg
Read (Multiple with Filter)
GET
Collection URI
/caisd-rest/chg?WC=status%3D6001
Read (Single ID)
GET
Entry URI
/caisd-rest/chg/400001
Read (Single COMMON_NAME)
GET
Entry URI
/caisd-rest/chg/COMMON_NAME-21
Read (Single REL_ATTR)
GET
Entry URI
/caisd-rest/chgstat/REL_ATTR-OP
Update
PUT
Entry URI
/caisd-rest/chg/40001
Delete
DELETE
Entry URI
/caisd-rest/grpmem/400001
COMMON_NAME and REL_ATTR are case-sensitive. If you do not use upper case, REST returns the HTTP-404 error code.
REST Considerations
Consider the following information about REST methods:
  • POST operations create a resource from the provided representation, but CA SDM can add or modify attribute values internally. These values are based on business object logic that attribute triggers, SPEL code, methods, or both set. The result causes the POST operation to return the actual representation that it created to the client. This behavior lets clients reconcile the representation that they sent to the server with the actual representation that they created.
  • For GET operations, enter
    %20
    instead of a space in the WHERE clause.
REST Limitations
The REST API does
not
support dotted attribute name references in its resource queries or attributes. REST does
not
expose any BREL, QREL or LREL attribute that contains a dotted attribute in its relationship query. For example, the chg object in base.maj contains the following QREL attributes:
workload_chg QREL chg DYNAMIC { WHERE "assignee = ? and active = 1" ; PARAM_NAMES { id } ; DOMSET chg_list; } ; change_tasks QREL wf DYNAMIC { WHERE "assignee = ? AND status.allow_task_update = 1 " ; PARAM_NAMES { id } ; DOMSET wf_list ; } ;
In this example, workload_chg QREL attributes are available. The change_tasks QREL is unavailable because it contains a dotted attribute (status.allow_task_update) in its WHERE clause.
REST and Object Access
Many CA SDM components consist of objects. A metalanguage named Majic defines these objects. Majic statements let you create objects and modify existing objects, so you can customize these objects to meet your business requirements. You can customize the exposure of the CA SDM objects through REST to determine the following:
  • Objects accessible through REST
  • Permitted operations for each object
After you install CA SDM, all objects are accessible through REST. The REST_OPERATIONS keyword specifies the operations that you can perform on an object. By default, all objects allow the CREATE, READ, and UPDATE operations. Some default objects also permit the DELETE operation, as indicated in the REST_OPERATIONS list in their object definition. You do
not
need to use the REST_OPERATIONS keyword for the default setup. You can refine object access to perform the following tasks:
  • Override the REST_OPERATIONS list by using a Majic MODIFY statement to remove or add operations, except for the DELETE operation.
    Note:
    You cannot add the DELETE operation to any default object.
  • Remove an object from REST entirely by specifying NONE in the REST_OPERATIONS list.
rest_access resource
The rest_access resource contains REST API access information for the authenticated users. It is an administrative table and contains the list of users allowed through the REST API.
The following list shows the deviations from the default behavior:
  • POST
    Creates a REST access object and returns access key, secret key and expiration date as part of default values.
  • GET
    Retrieves REST access information (except for secret key).
  • DELETE
    Deletes the REST access object.
  • PUT
    Does not allow updates to secret_key, access_key, and contact due to the Majic WRITE_NEW property.
REST_OPERATIONS Keyword
The Majic keyword, REST_OPERATIONS, uses a parenthesized list of tokens. These tokens let you specify the REST operations that are permitted for an object. You use an object definition and a MODIFY clause to customize the keyword.
The REST_OPERATIONS keyword has the following syntax:
REST_OPERATIONS "[<OP>],[<OP>] | NONE";
  • OP
    Specifies the CREATE, READ, UPDATE, and DELETE operations.
This keyword produces the following statements:
REST_OPERATIONS "CREATE, READ, UPDATE DELETE"; REST_OPERATIONS "NONE";
At run time, CA SDM allows overrides by using the following Majic MODIFY statement:
MODIFY FACTORY cr { REST_OPERATIONS "READ, UPDATE"; };
REST_OPERATIONS Syntax Examples
The following example modifies the cr object to limit the operations to READ and UPDATE. Any attempt to create or delete the object returns an error of
HTTP error code 405 Method Not Allowed
.
CA SDM sets the default value for a REST_OPERATIONS property as “CREATE READ UPDATE” for most Objects. For example, cr, iss, and chg. For some object, CA SDM sets the default REST_OPERATIONS value to “CREATE READ UPDATE DELETE.” For example, rest_access and KCAT.
MODIFY FACTORY cr { REST_OPERATIONS "READ UPDATE"; };
The following example removes announcements from REST completely:
MODIFY FACTORY cnote { REST_OPERATIONS "NONE"; };
Note:
You cannot use DELETE in a MODIFY statement. The NONE operation is standalone and not allowed with the CREATE READ UPDATE combination in the MODIFY statement.
REST API Servlet Settings
You can configure additional REST API settings in the web deployment descriptor
web.xml
file. The file
$NX_ROOT/site/rest/web.xml.tpl
is provided as a template and should not be modified. When you first start CA Service Desk Manager, it creates a
web.xml
file from the template into the same directory. You can modify this file, which is included in the WAR file to be deployed.
Available Parameters
ExternalBaseURI
This optional setting allows you to provide a custom REST API address for hyperlinks included in the response body. This is useful for sites that have load balancers, reverse proxy servers, external hostnames, https addresses, etc. Make sure the REST API web app name such as “caisd-rest” is included in this value. The sample default value is: http://host:8050/caisd-rest
Follow these steps:
  1. Stop all CA Service Desk Manager services.
  2. Navigate to the $NX_ROOT/site/rest/ folder and edit the
    web.xml
     file.
  3. Locate REST API external address section in the file and uncomment the following elements:
    <context-param>
    <param-name>ExternalBaseURI</param-name>
    <param-value>http://host:port_number/caisd-rest</param-value
    >
    </context-param>
    : Replace 
    host:port_number
     with an appropriate external address and port number.
  4. Save and close the file.
  5. Restart the CA Service Desk Manager services.
    You can recreate the file if Tomcat fails to start or report errors.
NULL Value in Update Operation
You can set the HTTP header 
X-AttrsToNull
 and assign a NULL value to an attribute for the update operations. This header takes a list of comma-separated attribute names. The header value takes precedence over the attributes in the request body in case of duplicates. BREL and QREL type attributes do not apply, but SREL attributes do.
Example 1
: Update the
call_back_date
attribute of a Request ticket to NULL. In this example, setting
call_back_date
to NULL requires that the
call_back_flag
is not equal to 1. 
HTTP URL: PUT /caisd-rest/cr/400055HTTP Header X-AttrsToNull: call_back_datePayload (XML): <cr><call_back_flag>0</call_back_flag></cr>
Example 2
: Update the email address to NULL for a contact.
HTTP URL: PUT /caisd-rest/cnt/U'ADE6396E2A3D9E4A958AC522521C5A35'HTTP Header X-AttrsToNull: email_addressPayload (XML): <cnt></cnt>
The examples above do not show all HTTP headers.
Working with BLRELs
The BLREL keyword refers to Majic attributes that point to an LREL table. These attributes are part of a three-factory relationship. BLREL attributes were known as LREL attributes in previous releases of CA SDM, but they have changed to BREL attributes. This name helps distinguish BLRELs from the classic BREL attributes which are only a two-factory relationship.
An example of this three-factory relationship is the group and members relationship. This relationship consists of a grp object, a cnt object, and the LREL table object that the grpmem object represents. In this three-factory relationship, two BLREL attributes always point to a common LREL table. In the group/member relationship, both BLREL attributes are frequently part of the same object, but not always.
The following example shows how CA SDM defines BLREL attributes in Majic files.
OBJECT cnt { ... member_list BREL grpmem group DYNAMIC { LREL member; } ; group_list BREL grpmem member DYNAMIC { LREL group; } ; }
You can always view the attributes of an object by executing the bop_sinfo command on an active system:
bop_sinfo -d grpmem
The LREL table record creates an association between records of two other tables. For the group/member relationship, the grpmem record is the LREL table that creates this association. It is a many-to-many relationship, where groups can have many members, and members can be part of many groups.
WHERE Clause Resource Search
REST Web Services let you use a
WC
(WHERE clause) query for the GET request. REST Web Services let you use a WC (WHERE clause) query for the GET request. REST supports the SQL query notation, and offers limited support to the Majic query notation. For example, the dotted attribute notation will pass if they have passed in other areas of the product (SOAP). If you do not add a WC parameter to the URL, all records return up to the page size and maximum size limits.
Consider the following information:
  • Use percent-encoding for all requests before you send them to the server. For example, enter
    %3D
    instead of
    =
    , the equals sign.
  • The WC parameter is part of the URI instead of a message header to allow bookmarking.
  • The WC query parameter only applies to Collection GET requests.
Example: Search for Contact Records with a Last Name that Equals ServiceDesk
http://<host>:<REST port>/caisd-rest/cnt?WC=last_name%3D'ServiceDesk'
Example: Search for Priority 2 Incidents
/in?WC=priority%3D4
The 4 value in the example specifies the REL_ATTR value for the Priority 2 record.
Use REL_ATTR values in the WC parameter when you reference SREL attributes such as priority.
Example: Search for Incidents that Contain test% in the Summary Field
/in?WC=summary%20LIKE%20'test%25'
Valid URI Path Patterns
Not all resource paths and subresource paths expose all four HTTP methods, depending on the URI path level and the resource. The following list shows the exposed methods:
  • /caisd-rest/<factory>
Example:
/caisd-rest/cr
GET searches for objects and returns a collection of objects.
POST creates an object and returns the object that you created.
  • /caisd-rest/<factory>/<object id>
Example:
/caisd-rest/cr/400001
GET returns details for one object.
PUT updates the object.
DELETE removes the object. If allowed.
  • /caisd-rest/<factory>/<object id>/<attribute name (SREL)>
Example:
/caisd-rest/chg/400001/status
GET returns Details for the SREL attribute object, same as going directly to the SREL object if you know the ID. For example, /caisd-rest/crs/5200
  • /caisd-rest/<object>/<object id>/<attribute name (BREL)>
Example:
/caisd-rest/chg/400001/act_log
GET returns a collection of objects of the type the BREL points to.
  • /caisd-rest/<factory>/<object id>/<attribute name (BLREL)>
Example:
/caisd-rest/chg/400001/attachments
GET returns a collection of objects of the type the BLREL points to (the LREL record).
  • /caisd-rest/<factory>/<object id>/<attribute name (QREL)>
Example:
/caisd-rest/chg/400001/workflow
GET returns a collection of objects of the type the QREL points to.
Search Result Sorting
CA SDM Web Services let you sort search results by using the SORT query parameter, included as part of the URI. You can specify a list of attributes as the sort order. You can also specify ASC for ascending order, or specify DESC for descending order.
For default behavior, the SORT parameter provides that same support that the DBMS provides for the ORDER BY clause. For example, if you omit ASC or DESC, the DBMS may use ASC automatically. If you do not provide a SORT parameter in the URI, the DBMS uses
id ASC
by default.
This behavior only applies to collection GET requests, such as the example:
GET http://<host>:<REST-port>/caisd-rest/<fac name> GET http://myserver:8080/caisd-rest/cr?SORT=priority DESC, severity ASC
Consider the following information:
  • You
    must
    encode all requests before sending them to the server. For example, enter
    %20
    instead of spaces.
  • All object attributes specified in the SORT parameter add to the X-Obj-Attrs list of object attributes automatically. This behavior helps ensure that the attributes selected for sorting are part of the response.
  • The SORT parameter is part of the URI instead of a message header to allow for bookmarking.
Note:
If you do not provide the X-Obj-Attrs header, id, REL_ATTR, and COMMON_Name list by default, as they always appear as part of the response.
Search Result Navigation
Provide ATOM links to improve navigating search and list results. These links take the user to the previous or next step when more records become available. By default, the Collection GET result contains up to 25 records. Use the rest_webservice_list_page_length and rest_webservice_list_max_length options to configure the page length and maximum number of records to display.
The ATOM links appear only for available records for that purpose. REST does not provide the
previous
link if the current page contains the first record in the list. Similarly, REST only provides the
next
and
all
links when you have more available records.
Users can also provide their own list return size with the
size
parameter. If the user does not provide
size
, REST defaults to the value of rest_webservice_list_page_length. If you do not provide start, REST defaults to 1.
Example Request Returns a Specific Number of Records
In this example, you request a return of 10 records:
http://myserver:8050/caisd-rest/cnt?start=11&size=10
If this result set contained 50 records, the following links appear:
<link href="http://myserver:8050/caisd-rest/cnt?start=1&size=10" rel="previous"/> <link href="http://myserver:8050/caisd-rest/cnt?start=21&size=10" rel="next"/> <link href="http://myserver:8050/caisd-rest/chg?start=1&size=50" rel="all"/>
Note:
When the result set contains more than the maximum number allowed, the all link does not appear.
HTTP Status and Error Codes
Every HTTP response contains an HTTP status code. Successful HTTP response code numbers range from 200 to 399. Standard HTTP error response code numbers range from 400 to 599.
The following list shows the successful and error code numbers that the REST API returns for each of the HTTP methods.
  • GET (single)
    200, 400, 401, 404, 409
  • GET (collection)
    200, 400, 401
  • PUT
    200, 400, 401, 404, 409
  • DELETE
    204, 400, 401, 409
  • POST
    201, 400, 401, 409
Note:
For the PUT and DELETE operations, the API does
not
try to determine the validity of the ID initially. Instead, the API tries to run the update and delete queries directly. If an error occurs, the API returns the
409 Conflict
code. If the API returns a
404 Not Found
code in this situation, performance degrades.
In addition, the following error messages return under the following cases:
  • If the HTTP request contains an invalid or inaccessible URI address, the server responds with a
    404 Not Found
    response code.
  • If the HTTP request contains an unsupported HTTP method for a valid URI, the server responds with a
    405 Method Not Allowed
    response code.
  • If the HTTP request requests an unsupported media type (Accept header), the server responds with a
    406 Not Acceptable
    response code.
  • If the HTTP request sends an unsupported media type (Content-Type header), the server responds with a
    415 Unsupported Media Type
    response code.
  • Various syntax or internal Web Server errors can return a 500 internal error.
Code Matching Limitations
Because of a limited number of available HTTP codes, not all CA SDM errors match to an HTTP error code. Matching errors return the corresponding HTTP error codes whenever possible, but most backend process errors return a generic
400 Bad Request
code. A message summarizes the error.
The following error messages match the corresponding HTTP error code. All others use error code 400.
  • A request for a resource that does not exist in CA SDM returns a
    404 Not Found
    error code.
  • A request for a resource that returns multiple matches, such as when using a nonunique COMMON_NAME value returns a
    409 Conflict
    error code.
  • A request for an unaccessible resource due to Authentication Failure or Function Access security return a
    401 Unauthorized
    error code.
Known Status Codes
The following list describes the known status codes that the API returns. Other codes may exist from the web server or the CXF framework, but it depends on the type of error.
  • 200
    OK
    Indicates a successful return.
  • 201
    Created
    Indicates a new record.
  • 204
    No Content
    Indicates an empty response body.
  • 304
    Not Modified
    Indicates that the record did not update.
  • 400
    Bad Request
    Indicates that an error occurred due to a user or backend server issue.
  • 401
    Unauthorized
    Indicates a function Access error or any authentication failure.
  • 404
    Not Found
    Indicates that a record is not found.
  • 405
    Method Not Allowed
    Indicates an unsupported HTTP method.
  • 406
    Not Acceptable
    Indicates an unsupported requested format.
  • 409
    Conflict
    Indicates that multiple records were found for the given identifier.
  • 415
    Unsupported Media Type
    Indicates that the provided format is not supported.
  • 500
    Internal Server Error
    Indicates an error on the server or CXF framework.
Atom Feeds
CA SDM supports Atom feeds through the collection GET URI path because Atom feeds represent a list of records. This implementation supports all query parameters that REST Web Services support, such as the WC, start, and size query parameters. This implementation supports two additional query parameters, EntryTitle and EntrySummary, which let you specify a mapping between the Atom entry Title and Summary elements to Majic attributes.
EntryTitle=<Majic attribute name> EntrySummary=<Majic attribute name>
Note:
If you do
not
specify these parameters, REST uses the COMMON_NAME as the default title and summary values.
The following sample displays these query parameters:
GET /caisd-rest/cnt?size=2&EntryTitle=userid&EntrySummary=notes HTTP/1.1 Accept: application/atom+xml
The following sample displays the Atom response:
<?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <author> <name>CA Service Desk Manager</name> </author> <title type="text">REST API Atom feed</title> <id>http://myserver:8050/caisd-rest/cnt</id> <updated>2012-01-17T17:56:04.301Z</updated> <link href="http://myserver:8050/caisd-rest/cnt?start=3&#38;size=2" rel="next"/> <link href="http://myserver:8050/caisd-rest/cnt?start=1&#38;size=12" rel="all"/> <link href="http://myserver:8050/caisd-rest/cnt" rel="self"/> <entry> <author> <name>CA Service Desk Manager</name> </author> <title type="text">System_AM_User</title> <id>http://myserver:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'</id> <updated>1970-01-01T00:00:00.000Z</updated> <summary type="text"> User for Asset Management Integration</summary> <content type="application/xml"> <cnt id="U'16226C765005B94E957E0F477DEF1B1C'" REL_ATTR="U'16226C765005B94E957E0F477DEF1B1C'" COMMON_NAME="System_AM_User" xmlns=""> <link href="http://myserver:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'" rel="self"/> </cnt> </content> </entry> <entry> <author> <name>CA Service Desk Manager</name> </author> <title type="text">cavizuser</title> <id>http://myserver:8050/caisd-rest/cnt/U'17DEA1027C7C3746B6F25DB6604EEE23'</id> <updated>1970-01-01T00:00:00.000Z</updated> <summary type="text">Username used by Visualizer for accessing CA Service Desk Manager using Web Services</summary> <content type="application/xml"> <cnt id="U'17DEA1027C7C3746B6F25DB6604EEE23'" REL_ATTR="U'17DEA1027C7C3746B6F25DB6604EEE23'" COMMON_NAME="System_CMDB_Visualizer_User" xmlns=""> <link href="http://myserver:8050/caisd-rest/cnt/U'17DEA1027C7C3746B6F25DB6604EEE23'" rel="self"/> </cnt> </content> </entry> </feed>
Additional REST Support when Requesting Data Formats
REST Web Services also supports other ways of specifying the representation format using the URI. The Web Services work similarly specifying the representation format in the Accept HTTP header.
Example 1:
GET /caisd-rest/chg/400001.xml HTTP/1.1
GET /caisd-rest/chg/400001.json HTTP/1.1
GET /caisd-rest/chg.feed HTTP/1.1
Example 2:
GET /caisd-rest/chg/400001?_type=xml HTTP/1.1
GET /caisd-rest/chg/400001?_type=json HTTP/1.1
GET /caisd-rest/chg?_type=atom HTTP/1.1
Consider the following information:
  • If the representation format is specified on the URI and through the “Accept” header, the one in the URI takes precedence over the Accept header.
  • If a representation format is not specified in any way, the representation returns in the XML format by default.
  • The
    _type=
    query parameter supersedes all parameters.
CA SDM Role Authorization
As with SOAP Web Services, part of the REST Web Services Access Key creation (login operation) includes verifying the user has authorization to access REST Web Services. In SOAP, the Web Service and API Role lookup field controls this verification in the Access Type detail form. In REST, a new lookup field named REST Web Service API Role controls the verification for REST. You can only associate one role to this field, and this field is the default role for the user. If this lookup field is empty, the users belonging to this Access Type do not have access to CA SDM through the REST Web Services interface.
In addition, REST Web Services supports the same list of Attached Roles that are part of the Web Client interface. A REST user can select a different role from the list of Attached Roles (including the roles in its Contact record) by passing in an additional message header as part of the request.
Example: Use the Administrator role for the request
POST /caisd-rest/cnt HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2011 19:37:58 +0000 X-Role: 10002
REST Java Sample Code
CA SDM provides REST Java sample code in the NX_ROOT\samples\sdk\rest\java directory. These sample files let you build custom Java client code in your environment, similar to SOAP web service samples. This directory contains instructions for compiling and executing the sample programs in the README.txt file. Each Java file documents additional instructions and sample input parameters. The following directories in \rest\java provide the following samples:
  • test1_basic
  • SampleBasicAuth.java
    Demonstrates how to get an Access Key using a username/password through the Basic Authentication scheme.
  • SampleCRUDOperations.java
    Demonstrates how to perform simple CRUD operations (Create, Read, Update and Delete) on Incident tickets. The same can be used for any other object in CA SDM.
  • test2_auths
  • SampleBOPSIDAuth.java
    Demonstrates how to get an Access Key using a BOPSID token. This CA SDM token can be obtained from other CA SDM Interfaces such as SOAP Web Services.
  • SampleEEMAuth.java
    Demonstrates how to get an Access Key using an CA EEM artifact/token. This token can be obtained from other applications that use CA EEM as their authentication server.
  • SampleSDMAuth.java
    Demonstrates how to get an Access Key and a Secret Key using a username/password through the CA SDM custom authentication scheme.
  • SampleUsingSecretKey.java
    Demonstrates how to make a REST API request (get a list of Contacts) using the Secret Key. It uses the Secret Key obtained from the CA SDM custom authentication operation to encrypt a configurable amount of data. All requests using this scheme are verified against the Secret Key.
  • test3_attachments
  • SampleNewResourceWithAttachment.java
    Demonstrates how to create a new Change Order ticket with an attachment document all in one step.
  • SampleAttachFileToResource.java
    Demonstrates how to attach a document to an existing Change Order ticket.
  • test4_xrels
  • SampleGetQRELDetails.java
    Demonstrates how to retrieve details on a QREL attribute. In this sample, details for chg.children are retrieved. The same approach works for BREL and BLREL attributes.
  • SampleCreateBRELResource.java
    Demonstrates how to create a new record for a BREL attribute. In this sample, a new Log Comment activity is added to an existing Change Order. The same approach works for creating a new record for BLREL attributes.
Build and Execute the Sample Programs
You can build and execute the sample Java programs to test them in your environment.
Follow these steps:
  1. Copy rest_java_test.bat.txt (Windows) or rest_java_test.sh.txt (UNIX) to the subdirectory where the sample program exists.
  2. Rename the copied file by removing the .txt extension.
  3. Edit the copied file and verify that the first three SET variables are correct for your CA SDM installation.
  4. In addition, edit the Java file that you want to run and verify that the configurable variables are set for your CA SDM installation. Also, read the comments at the top of the page.
CA SDM Authentication Scheme
CA SDM provides sample code in the NX_ROOT/samples/sdk/rest/java directory. This directory also contains instructions about how to compile and execute the sample programs. REST Web Services support the following security authentication schemes:
REST Secret Key Authentication
REST Secret Key authentication uses a custom, secure HMAC mechanism. This authentication lets CA SDM verify the identity of a user and also verifies that the request came from a registered, verified user. To complete this authentication successfully, each request must provide information about the identity of the request sender.
HMAC_ALGORITHM supports the HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512, and HmacMD5 valid HMAC algorithms. By default, REQUEST_METHOD, REQUEST_URI, and QUERY_STRING (if present) are used to compute the signature. You can also use other header fields to compute the signature, such as date, x-obj-attrs, and content-type. To add these fields set the following NX variable in NX.env file:
@NX_STRING_TO_SIGN_FIELDS=date,x-obj-attrs,content-type
Note:
When you compute the signature on the Client side, use the same fields exactly in the same order as specified the fields for the STRING_TO_SIGN_FIELDS option.
  • Access Key
    The Access Key is an assigned value to CA SDM clients after a successful login authentication. Requests use the Access Key to identify the client responsible for the request. However, because an Access Key is sent as a request parameter, the Access Key is not secret. A possibility exists that anyone could use the Access Key by sending a request to CA SDM. As a result, this authentication requires a Secret Key. REST uses the CA SDM session ID as the Access Key.
  • Secret Key
    After you log in to CA SDM successfully, the product assigns a Secret Key and Access Key to the client. To protect users from impersonation, the client must provide additional information that CA SDM can use to verify the identity. CA SDM generates the 40-character Secret Key during the REST Access Key creation automatically.
The following steps describe the authentication process:
  1. The client obtains the Access Key and Secret Key through the REST URI (POST /caisd-rest/rest_access) by providing user credentials using the basic authentication style over SSL.
  2. For every subsequent HTTP request, the client uses the Secret Key, NX_STRING_TO_SIGN_FIELDS provides the header fields, and the NX_HMAC_ALGORITHM variable provides the hash function. This function calculates the request signature, a Keyed-Hash based Message Authentication Code (HMAC).
  3. The client sends the request data, the signature, and the Access Key to CA SDM.
  4. CA SDM uses the Access Key to look up the Secret Key from the persistence store.
  5. CA SDM uses the request data and the Secret Key to generate the signature using the same hash algorithm that the client used.
  6. If the signature that CA SDM generates matches the signature that the Client sent, CA SDM considers the request as authentic. Otherwise, CA SDM discards the request and returns an error response.
REST BOPSID Authentication
After a user logs in to CA SDM through one interface, they can access CA SDM from a different interface by using a BOPSID token. The BOPSID token provides a way for the invoked application to authenticate the user without requiring a login, such as Single Sign-On. After CA SDM authenticates a user, the application can request a BOPSID from boplgin. This single-use token identifies the user and session. Boplgin returns the userid and session when it receives the BOPSID. Boplgin also cancels the BOPSID if it does not receive a verification request within 5 minutes of token creation.
The following example shows the HTTP message header for passing the BOPSID token:
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2012 19:37:58 +0000 X-BOPSID: <BOPSID token>
Note:
To obtain a BOPSID token through REST Web Services, you send a POST request to /caisd-rest/bopsid.
REST Basic Authentication
The basic authentication scheme assumes that the credentials of a client contain a username and password, where the password is a secret known only to the client and server.
If the incoming request does not contain the client credentials, the server sends back a 401 response that contains an authentication challenge. This challenge consists of the "Basic" token and a name-value pair that specifies the name of the protected realm, such as the following example:
WWW-Authenticate: Basic realm="<USDK> 12.9"
After receiving the 401 response from the server, the client (such as a browser) prompts for the username and password associated with that realm. The Authentication header of the client follow-up request should contain the "Basic" token and the base64-encoded group of the username, password, and a colon.
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2012 19:37:58 +0000 Authorization: Basic QWRtaW46Zm9vYmFy
REST decodes credentials using base64 and compares them against the username/password and validates the credentials through boplgin. If this validation succeeds, the server provides access to the requested resource.
If the user sends the BOPSID instead of the username and password, CA SDM uses the the boplgin method validate_bopsid(). If you are concerned about using basic authentication scheme, you can disable it by setting the Options Manager option NX_REST_WEBSERVICE_DISABLE_BASIC_AUTH to Yes.
Important! Basic authentication is not as secure as the Secret Key method. However, you can use Basic authentication over an SSL connection for increased security.
External CA EEM Artifact Authentication
You can use CA EEM Artifact Authentication for REST requests. Clients send the CA EEM Artifact with the username using predefined customer headers (X-ExtAuthArtifact, X-UserName). When this header entry appears in an incoming request, the security interceptor performs the login validation by sending a VALIDATE_ARTIFACT message to boplgin.
The following example shows how to use the CA EEM Artifact:
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Date: Mon, 21 Apr 2012 19:37:58 +0000 X-ExtAuthArtifact: <EEM Artifact token> X-UserName: <username>
CRUD Operations on Tickets
The REST API provides sample Java code for the user to work with tickets through the REST API. These files contain the following operations:
  • Create a Change Order with hard-coded sample data.
  • Update a recent Change Order with a status update.
  • Create an Incident and display the Incident number on the console.
  • Get a list of Incident numbers using a where clause and display on the console.
BREL, QREL, and BLREL Processing
The REST API provides the sample Java code for the user to work with tickets through the REST API with BREL and QREL attributes. The BREL, QREL, and BLREL attributes only support the Get operation. The files contain the following operations:
  • Create BREL using the documented, multi-step process. For example, add activity logs to a Change Order. For QREL, create multiple Change Orders as children to a Change Order. For BLREL, add multiple CIs to a Change Order.
  • Get a list of attributes that returns the URI for a BREL, QREL, or BLREL attribute, and display them on the console.
  • Get the collection of the BREL, QREL, or BLREL attribute with the URI and display it on the console. For example, /caisd-rest/chg/40001/act_log.
Managing Attachments for Tickets
The REST API provides the sample Java code for the user to work with tickets through the REST API. The files contain the following operations:
  • Create an Incident.
  • Create an attachment.
  • Add the attachment to the Incident (2 step).
  • Create an Incident with the attachment (1 step).
  • Delete the attachment from the Incident.
  • Download an Attachment
    Perform the following to download an attachment file:
    1. To download a file, issue the following command line request:
      GET /caisd-rest/attmnt/<attmnt id>/file-resource
      Where 'file resource' is the plain text
      For example, to download a file associated with the attachment record 400015, issue the following request:
      GET /caisd-rest/attmnt/400015/file-resource
      The response content type for file downloads is
      application/octet-stream. 
      A client such as Apache Commons HTTP Client can easily handle this content type. For a complete working sample using Apache Commons HTTP Client, check
      SampleDownloadAttachment.java
       file located in the 
      NX_ROOT\samples\sdk\rest\java\test3_attachments
      directory.
CA SDM Resource Examples
Examples demonstrate how REST API uses basic Create, Read, Update, and Delete (CRUD) HTTP operations on CA SDM objects. Use the examples to understand how each REST operation works in the same manner on all CA SDM objects.
For readability, the examples do not show all HTTP message headers -- only the relevant information.
Example Create a Change Order With an Attachment
This REST API example provides a complex use case: create a change order ticket and an attachment.
MIME types application/xml and text/xml are often used interchangeably. We recommend that you use application/xml. All text/*-MIME types have an us-ascii character set unless otherwise explicitly specified in the HTTP headers. In effect, any encoding defined in the XML prolog (for example, <?xml version=”1.0” encoding=”UTF-8”?>) is ignored.
The following example shows the request:
POST /caisd-rest/chg/?repositoryId=1002&AttachmentId=att1&serverName=HOSTNAME&mimeType=doc&description=Desc HTTP/1.1 Content-Type: multipart/form-data X-AccessKey: 51461077 User-Agent: Jakarta Commons-HttpClient/3.0.1 Host: hostname:8050 Content-Length: 1045 --Vschb1Sy2JD93ODUnWVAkRxp3IoXIMgXd Content-Disposition: form-data; name="chg" Content-Type: application/xml; charset=US-ASCII Content-Transfer-Encoding: 8bit <chg><description>Attachments Testing</description><status COMMON_NAME="RFC" REL_ATTR="RFC" id="40020"><link rel="self" href="http://hostname:8050/caisd-rest/chgstat/40020"/></status><summary>Attachment test</summary><requestor COMMON_NAME="ServiceDesk" REL_ATTR="U'279B25DD051D0A47B54880D86700397F'" id="U'279B25DD051D0A47B54880D86700397F'"><link rel="self" href="http://hostname:8050/caisd-rest/cnt/U'279B25DD051D0A47B54880D86700397F'"/></requestor></chg> --Vschb1Sy2JD93ODUnWVAkRxp3IoXIMgXd Content-Disposition: form-data; name="Test.txt"; filename="Test.txt" Content-Type: application/octet-stream; charset=ISO-8859-1 Content-Transfer-Encoding: binary
The following example shows the response:
 
HTTP/1.1 201 Created Content-Type: application/xml;charset=UTF-8 Location: http://hostname:8050/caisd-rest/chg/400202 <chg id="400202" REL_ATTR="400202" COMMON_NAME="1047"> <link href="http://hostname:8050/caisd-rest/chg/400202" rel="self"/> </chg>
Example Create a Resource
This REST API example demonstrates how to create a resource. In this example, the REST API creates a change order ticket.
The following example shows the request:
POST /caisd-rest/chg HTTP/1.1 Host: hostname Accept: application/xml Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: chg_ref_num <chg> <summary>Created via REST API</summary> <requestor REL_ATTR="U'793ED69B4E87A545BD8E911834D829FC'"/> </chg>
 
The following example shows the response:
HTTP/1.1 201 Created Content-Type: application/xml;charset=UTF-8 Location: http://hostname:8050/caisd-rest/chg/400001 <?xml version="1.0" encoding="UTF-8"?> <chg id="400003" REL_ATTR="400003" COMMON_NAME="23"> <link href="http://hostname:8050/caisd-rest/chg/400003" rel="self"/> <chg_ref_num>23</chg_ref_num> </chg>
Example Delete a Resource
This REST API example demonstrates how to delete a resource.
Not all objects are available for deletion. Most objects only support updating the delete_flag to true or false, or status equal to active or inactive. You perform these actions using an UPDATE request rather than a DELETE request.
 
The following example shows the request:
DELETE /caisd-rest/grpmem/400001 HTTP/1.1 Host: hostname
 
The following example shows the response:
HTTP/1.1 204 No Content Content-Type: application/xml;charset=UTF-8 Content-Length: 0
Example Delete an Access Key
This REST API example demonstrates how to delete a CA SDM access key.
The following example shows the request:
DELETE /caisd-rest/rest_access/1201703106 HTTP/1.1 Host: hostname
The following example shows the response:
HTTP/1.1 204 No Content Content-Type: application/xml;charset=UTF-8 Content-Length: 0
Example Mark a Resource Inactive
This REST API example demonstrates how to mark a resource as inactive.
Most CA SDM objects only support marking them inactive and not actually deleting them.
The following example shows the request:
PUT /caisd-rest/loc/U'0502D608F9122B48B7C9DAB9E0457F94' HTTP/1.1 Host: hostname Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: delete_flag <loc id="U'0502D608F9122B48B7C9DAB9E0457F94'"> <delete_flag COMMON_NAME="Inactive"/> </loc>
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <loc id="U'0502D608F9122B48B7C9DAB9E0457F94'" REL_ATTR="U'0502D608F9122B48B7C9DAB9E0457F94'" COMMON_NAME="Stadium 1"> <link href="http://hostname:8050/caisd-rest/loc/U'0502D608F9122B48B7C9DAB9E0457F94'" rel="self"/> <delete_flag id="4552" REL_ATTR="1" COMMON_NAME="Inactive"> <link href="http://hostname:8050/caisd-rest/actbool/4552" rel="self"/> </delete_flag> </loc>
Example Obtain a BOPSID Token
A BOPSID token is single use authentication token that provides a single sign-on capability. This REST API example demonstrates how to obtain a BOPSID token to use for logging in to the web client.
The following example shows the request:
POST /caisd-rest/bopsid HTTP/1.1 Host: hostname.ca.com Accept: application/xml <bopsid/>
The following example shows the response:
HTTP/1.1 201 OK Content-Type: application/xml;charset=UTF-8 <bopsid> <bopsid_val>987982618</bopsid_val> </bopsid>
Example Obtain an Access Key
This REST API example demonstrates how to obtain an access key (login) for userid ServiceDesk. Perform this operation using SSL to avoid risking an unauthorized user stealing your secret key. Keep the force_unique_userid Options Manager option enabled at all times. When you disable this option, and multiple contact records with the same login ID exist, problems with data partitions, multi-tenancy, security, and other functions can occur.
The following example shows the request:
POST /caisd-rest/rest_access HTTP/1.1 Host: hostname Content-Type: application/xml;charset=UTF-8 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== <rest_access/>
The <rest_access/> shown above must come in the REST Request Body. 
The following example shows the response:
HTTP/1.1 201 Created Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <rest_access id="400001" REL_ATTR="400001" COMMON_NAME="770921656"> <link href="http://hostname:8050/caisd-rest/rest_access/400001" rel="self"/> <access_key>770921656</access_key> <expiration_date>1335276895</expiration_date> </rest_access>
Example Retrieve a Collection of Resources
This REST API example demonstrates how to retrieve a collection of resources. In this example, the REST API retrieves a collection of all change order ticket objects.
The root node (for example, collection_chg) also has other link elements such as previous, next, and all for navigating lists.
The following example shows the request:
GET /caisd-rest/chg HTTP/1.1 Host: hostname Accept: application/xml
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_chg> <chg id="400001" REL_ATTR="400001" COMMON_NAME="21"> <link href="http://hostname:8050/caisd-rest/chg/400001" rel="self"/> </chg> <chg id="400002" REL_ATTR="400002" COMMON_NAME="22"> <link href="http://hostname:8050/caisd-rest/chg/400002" rel="self"/> </chg> </collection_chg>
Example Retrieve a Collection of Resources Using a Where Clause
This REST API example demonstrates how to retrieve a collection of resources using a where clause. In this example, the REST API retrieves a collection of all request (cr) ticket objects with the Closed status.
BREL queries are supported.
The following examples show the request:
GET /caisd-rest/cr?WC=status%3D'cl' GET /caisd-rest/cr?WC=status%3D'op'%20and%20active%3D0 Host: hostname Accept: application/xml X-Obj-Attrs: ref_num, priority
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_cr COUNT="3" TOTAL_COUNT="3"> <cr id="2903" REL_ATTR="cr:2903" COMMON_NAME="AM:12"> <link href="http://hostname:8050/caisd-rest/cr/2903" rel="self"/> <priority id="502" REL_ATTR="3" COMMON_NAME="3"> <link href="http://hostname:8050/caisd-rest/pri/502" rel="self"/> </priority> <ref_num>AM:12</ref_num> </cr> <cr id="2907" REL_ATTR="cr:2907" COMMON_NAME="AM:14"> <link href="http://hostname:8050/caisd-rest/cr/2907" rel="self"/> <priority id="502" REL_ATTR="3" COMMON_NAME="3"> <link href="http://hostname:8050/caisd-rest/pri/502" rel="self"/> </priority> <ref_num>AM:14</ref_num> </cr> <cr id="3105" REL_ATTR="cr:3105" COMMON_NAME="UAPM:13"> <link href="http://hostname:8050/caisd-rest/cr/3105" rel="self"/> <priority id="502" REL_ATTR="3" COMMON_NAME="3"> <link href="http://hostname:8050/caisd-rest/pri/502" rel="self"/> </priority> <ref_num>UAPM:13</ref_num> </cr> </collection_cr>
Example Retrieve a Specific Resource
This REST API example demonstrates how to retrieve a specific resource using ID, COMMON_NAME, or REL_ATTR. In this example, the REST API retrieves details about the unique change order ticket object ID 400001.
The following example shows the request when you use ID:
GET /caisd-rest/chg/400001 HTTP/1.1 Host: hostname.ca.com Accept: application/xml X-Obj-Attrs: chg_ref_num, summary, requestor, status
The following example shows the request when you use COMMON_NAME:
GET /caisd-rest/chg/COMMON_NAME-32 HTTP/1.1
The following example shows the request when you use REL_ATTR:
GET /caisd-rest/chg/REL_ATTR-chg:400001 HTTP/1.1
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <chg id="400001" REL_ATTR="400001" COMMON_NAME="21"> <link href="http://hostname:8050/caisd-rest/chg/400001" rel="self"/> <chg_ref_num>21</chg_ref_num> <requestor id="U'793ED69B4E87A545BD8E911834D829FC'" REL_ATTR="U'793ED69B4E87A545BD8E911834D829FC'" COMMON_NAME="System_AHD_generated"> <link href="http://hostname:8050/caisd-rest/cnt/U'793ED69B4E87A545BD8E911834D829FC'" rel="self"/> </requestor> <status id="40020" REL_ATTR="RFC" COMMON_NAME="RFC"> <link href="http://hostname:8050/caisd-rest/chgstat/40020" rel="self"/> </status> <summary>Testing</summary>
Example Retrieve a Subresource
This REST API example demonstrates how to retrieve a subresource.
The following example shows the request:
GET /caisd-rest/chg/400001/status HTTP/1.1 Host: hostname Accept: application/xml X-Obj-Attrs: code, sym, description HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <chgstat id="40020" REL_ATTR="RFC" COMMON_NAME="RFC"> <link href="http://hostname:8050/caisd-rest/chgstat/40020" rel="self"/> <code>RFC</code> <description>Request for Change is in draft form</description> <sym>RFC</sym> </chgstat>
Example Update a Resource
This REST API example demonstrates how to update a resource. In this example, the REST API updates the summary field for the change order ticket ID 400003.
The following example shows the request:
PUT /caisd-rest/chg/400003 HTTP/1.1 Host: hostname Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: chg_ref_num, summary <chg id="400003"> <summary>Summary updated via REST API</summary> </chg>
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0" encoding="UTF-8"?> <chg id="400003" REL_ATTR="400003" COMMON_NAME="23"> <link href="http://hostname:8050/caisd-rest/chg/400003" rel="self"/> <chg_ref_num>23</chg_ref_num> <summary>Summary updated via REST API</summary> </chg>
Example Get a BLREL Record
This example shows how to retrieve a BLREL record:
The following example shows the request:
GET /caisd-rest/grpmem HTTP/1.1 Host: localhost Accept: application/xml X-Obj-Attrs: *
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_grpmem COUNT="3" START="1" TOTAL_COUNT="3"> <grpmem id="400001" REL_ATTR="grpmem:400001" COMMON_NAME="400001"> <link href="http://localhost:8050/caisd-rest/grpmem/400001" rel="self"/> <group id="U'CFCC2DC94B3A66448C085B07E7286CAA'" REL_ATTR="U'CFCC2DC94B3A66448C085B07E7286CAA'" COMMON_NAME="Unicef"> <link href="http://localhost:8050/caisd-rest/grp/U'CFCC2DC94B3A66448C085B07E7286CAA'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'3F05B7450203AD449BFB8088D991A03E'" REL_ATTR="U'3F05B7450203AD449BFB8088D991A03E'" COMMON_NAME="System_SD_User"> <link href="http://localhost:8050/caisd-rest/cnt/U'3F05B7450203AD449BFB8088D991A03E'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400001</persistent_id> <producer_id>grpmem</producer_id> </grpmem> <grpmem id="400002" REL_ATTR="grpmem:400002" COMMON_NAME="400002"> <link href="http://localhost:8050/caisd-rest/grpmem/400002" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://localhost:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'FCF9A8AC6381AA4386C9B10EE382E10B'" REL_ATTR="U'FCF9A8AC6381AA4386C9B10EE382E10B'" COMMON_NAME="System_MA_User"> <link href="http://localhost:8050/caisd-rest/cnt/U'FCF9A8AC6381AA4386C9B10EE382E10B'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400002</persistent_id> <producer_id>grpmem</producer_id> </grpmem> <grpmem id="400003" REL_ATTR="grpmem:400003" COMMON_NAME="400003"> <link href="http://localhost:8050/caisd-rest/grpmem/400003" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://localhost:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'16226C765005B94E957E0F477DEF1B1C'" REL_ATTR="U'16226C765005B94E957E0F477DEF1B1C'" COMMON_NAME="System_AM_User"> <link href="http://localhost:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400003</persistent_id> <producer_id>grpmem</producer_id> </grpmem> </collection_grpmem>
This sample returns three grpmem records that represent the following associations:
  • Group Unicef <-> Member System_SD_User
  • Group Apache <-> Member System_MA_User
  • Group Apache <-> Member System_AM_User
Example Retrieve a List of LREL Records Associated with a Group
The following example returns two grpmem records associated with the Group Apache whose REL_ATTR value is U'55E3CCE805756B4F8084D63E05E6C216'. Note that
  • Group Apache <-> Member System_MA_User
  • Group Apache <-> Member System_AM_User
The following example shows the request:
GET /caisd-rest/grpmem?WC=group%3DU%2755E3CCE805756B4F8084D63E05E6C216%27 HTTP/1.1 Host: hostname Accept: application/xml X-Obj-Attrs: *
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <collection_grpmem COUNT="2" START="1" TOTAL_COUNT="2"> <grpmem id="400002" REL_ATTR="grpmem:400002" COMMON_NAME="400002"> <link href="http://hostname:8050/caisd-rest/grpmem/400002" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'FCF9A8AC6381AA4386C9B10EE382E10B'" REL_ATTR="U'FCF9A8AC6381AA4386C9B10EE382E10B'" COMMON_NAME="System_MA_User"> <link href="http://hostname:8050/caisd-rest/cnt/U'FCF9A8AC6381AA4386C9B10EE382E10B'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400002</persistent_id> <producer_id>grpmem</producer_id> </grpmem> <grpmem id="400003" REL_ATTR="grpmem:400003" COMMON_NAME="400003"> <link href="http://hostname:8050/caisd-rest/grpmem/400003" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'16226C765005B94E957E0F477DEF1B1C'" REL_ATTR="U'16226C765005B94E957E0F477DEF1B1C'" COMMON_NAME="System_AM_User"> <link href="http://hostname:8050/caisd-rest/cnt/U'16226C765005B94E957E0F477DEF1B1C'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400003</persistent_id> <producer_id>grpmem</producer_id> </grpmem> </collection_grpmem>
Example Create a BLREL Record
The following example adds an existing contact System_SA_User as a member of group Apache. It uses the COMMON_NAME value of each of those records.
Group Apache <-> Member System_SA_User
The following example shows the request:
POST /caisd-rest/grpmem HTTP/1.1 Host: hostname Accept: application/xml Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: * <grpmem> <group id="U'55E3CCE805756B4F8084D63E05E6C216'"/> <manager_flag>0</manager_flag> <member id="U'E70DFE4817614C06BE9E5991A96A6015'"/> <notify_flag>1</notify_flag> </grpmem>
The following example shows the response:
HTTP/1.1 201 Created Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <grpmem id="400005" REL_ATTR="grpmem:400005" COMMON_NAME="400005"> <link href="http://hostname:8050/caisd-rest3/grpmem/400005" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest3/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>0</manager_flag> <member id="U'E70DFE4817614C06BE9E5991A96A6015'" REL_ATTR="U'E70DFE4817614C06BE9E5991A96A6015'" COMMON_NAME="System_SA_User"> <link href="http://hostname:8050/caisd-rest3/cnt/U'E70DFE4817614C06BE9E5991A96A6015'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400005</persistent_id> <producer_id>grpmem</producer_id> </grpmem>
Example Update a BLREL Record
The following example updates the relationship of the added record and sets member System_SA_User as a Manager.
The following example shows the request:
PUT /caisd-rest/grpmem/400005 HTTP/1.1 Host: hostname Accept: application/xml Content-Type: application/xml;charset=UTF-8 X-Obj-Attrs: * <grpmem> <manager_flag>1</manager_flag> </grpmem>
 
The following example shows the response:
HTTP/1.1 200 OK Content-Type: application/xml;charset=UTF-8 <?xml version="1.0" encoding="UTF-8"?> <grpmem id="400005" REL_ATTR="grpmem:400005" COMMON_NAME="400005"> <link href="http://hostname:8050/caisd-rest3/grpmem/400005" rel="self"/> <group id="U'55E3CCE805756B4F8084D63E05E6C216'" REL_ATTR="U'55E3CCE805756B4F8084D63E05E6C216'" COMMON_NAME="Apache"> <link href="http://hostname:8050/caisd-rest3/grp/U'55E3CCE805756B4F8084D63E05E6C216'" rel="self"/> </group> <manager_flag>1</manager_flag> <member id="U'E70DFE4817614C06BE9E5991A96A6015'" REL_ATTR="U'E70DFE4817614C06BE9E5991A96A6015'" COMMON_NAME="System_SA_User"> <link href="http://hostname:8050/caisd-rest3/cnt/U'E70DFE4817614C06BE9E5991A96A6015'" rel="self"/> </member> <notify_flag>1</notify_flag> <persistent_id>grpmem:400005</persistent_id> <producer_id>grpmem</producer_id> </grpmem>
Example Delete a BLREL Record
The following example removes member System_MA_User from group Apache. This example does not delete the member record or the group record. It only removes the association between them. It does physically remove the grpmem record.
The following example shows the request:
DELETE /caisd-rest/grpmem/400002 HTTP/1.1 Host: hostname
The following example shows the response:
HTTP/1.1 204 No Content Content-Type: application/xml;charset=UTF-8 Content-Length: 0
 
Additional REST API settings can be configured via web deployment descriptor web.xml file. File $NX_ROOT\site\rest\web.xml.tpl is provided as a template and should not be modified. On first run, SDM will create a new file web.xml from template into the same directory. Users can modify this file, which will be included in the WAR file to be deployed. Updating Servlet Configuration Parameters To make updates, perform the following steps: * Shutdown SDM * Open file $NX_ROOT/site/rest/web.xml for editing * Find the parameter to be updated inside <param-name> tag * Carefully update the value inside corresponding <param-value> tag * Save file * Startup SDM If for any reason, REST Tomcat fails to start or reports errors due to the above changes, you can start fresh by creating a new web.xml file from template $NX_ROOT/site/rest/web.xml.tpl. Available Parameters ExternalBaseURI This optional setting allows you to provide a custom REST API address for hyperlinks included in the response body. This is useful for sites that have load balancers, reverse proxy servers, external hostnames, https addresses, etc. Make sure the REST API web app name such as “caisd-rest” is included in this value. The sample default value is http://host:8050/caisd-rest