Integrate > Service Manager integration methods and tools > Web Services > RESTful API > Consuming Service Manager RESTful API > Attachment operations using the RESTful API

Attachment operations using the RESTful API

Service Manager supports all typical attachment operations using its web services (SOAP API) or RESTful API. These operations include: get attachment information, get (single) attachment, delete (single) attachment, insert attachment, and so on.

The following topics describes how to perform typical attachment operations by using the RESTful API. It provides information about the services published by Service Manager, and explains requests of an external application being sent to Service Manager, as well as the responses to expect.

Tip This topic describes attachment operations that you can perform using the Service Manager REST API. For information about attachment operations using the Service Manager web services, see Attachment operations using the SOAP API.

When an external system sends a RESTful request, you can first look at the service document:

http://<SM server>:<port>/SM/9/rest

Information of RESTful services of all available objects can be found in the document retrieved. The following table contains the part returned for Incident.

Resource type Supported methods URI
Resource Collection GET/POST http://localhost:13080/SM/9/rest/incidents
Single Resource GET/POST/PUT http://localhost:13080/SM/9/rest/incidents/{number}
Resource Attachment Collection GET/POST/DELETE http://localhost:13080/SM/9/rest/incidents/{number}/attachments
Resource Single Attachment GET/PUT/DELETE http://localhost:13080/SM/9/rest/incidents/{number}/attachments/{id}

The target object of a request is determined by the URI, and the operation executed is determined by the HTTP method of the request. The table above lists supported methods.

Examples:

  • A GET request on the Resource Attachment Collection URI returns a JSON document with all the attachments IDs.
  • A GET request on the Resource Single Attachment URI downloads the attached file identified by ID.
  • A DELETE request on the Resource Single Attachment URI deletes the file attachment identified by ID.

Tip You can enter a GET HTTP message in the address bar of the browser, which is comfortable for testing. In order that Service Manager accepts these requests, enable the restaccessviabrowser:1 parameter for the servlet. For REST requests using other HTTP methods such as GET, testing in the browser address bar is impossible. You can use tools for web services testing or use available browser plugins for testing.

Retrieve attachment information

Execute a GET request on the Resource Attachment Collection of an incident identified by incident number.

http://localhost:13080/SM/9/rest/incidents/IM10003/attachments

The response received is a JSON document that resembles the following:

{
  "@count": 29,
  "@start": 1,
  "@totalcount": 29,
  "Messages": [
    "1: undefined",
    "0: undefined",
    "vars.$smtestmessages: [C++ object Datum] - ",
    "vars.$smtestresult: [C++ object Datum] - {NULL, NULL, NULL}"
  ],
  "ResourceName": "attachment",
  "ReturnCode": 0,
  "content": [
    {"attachment": {
      "href": "cid:58ac7b3200242211802b29a8",
      "len": 23146,
      "name": "error.log",
      "type": "multipart/form-data; boundary=\"----=_Part_32_596452009.1487698738148\"",
      "xmime:contentType": "multipart/form-data; boundary=\"----=_Part_32_596452009.1487698738148\""
}},




    [ .. ]



}

In this example, incident IM10003 has 29 attachments, and for each the JSON document contains information such as the attachment id (href), length in bytes (len), file name (name), file type (type), and xmime type (xmime:contentType).

Download an attached file

With the attachment information retrieved, you can find the attachment id (href attribute) and then send a GET request to download the attachment file:

http://localhost:13080/SM/9/rest/incidents/IM10001/attachments/58ac7b3200242211802b29a8

If you test this using a browser, the browser should show that a file is being downloaded.

Delete an attachment

When sending the same URI with HTTP method DELETE instead of GET, the attachment is deleted.

This is not possible by using the browser address bar, and therefore either a tool or plugin is required, or implementation like HTML page with JavaScript implementation is required.

The following is a demonstration HTML page to demonstrate deleting an attachment by using a REST request.

Note Your browser may not allow access because of security restrictions. To learn more, you can search for online information about "Cross-Origin Resource Sharing".

<!DOCTYPE html>
<html>
 
<head>
  <script language="javascript">
 
function sendrequest(method, url, contenttype, user, password, sync, request, callback)
{
 
 // Create a XMLHttpRequest object
  var ajax = null;
  if(window.XMLHttpRequest){          //Google Chrome, Mozilla Firefox, Opera, Safari, IE 10
         ajax = new XMLHttpRequest();
  }
  else
  {
       return;
  }
 
  // Add data to ajax object
  ajax.open( method, url, sync, user, password );
 
  if (contenttype) ajax.setRequestHeader("Content-Type", contenttype);
 
  if (!sync)
  {
      // Define how response will be processed
      ajax.onreadystatechange = function()
      {
         var result = {};
 
         switch (this.readyState)
          {
           case 0: result.status = "ReadyState: " + this.readyState; break;
           case 1: result.status = "ReadyState: " + this.readyState; break;
           case 2: result.status = "ReadyState: " + this.readyState; break;
           case 3: result.status = "ReadyState: " + this.readyState; break;
           case 4:
            {
               var result = {};
               result.status = ajax.status;
               result.response = ajax.responseText;
 
               if (callback) callback(result);
 
               break;
            }
         }
 
         updatePage(result.status, result.response);
 
         return result;
      }
  }
 
  // send the request
  if (request)  ajax.send( request );
  else ajax.send();
 
  if (sync)
  {
      var result = {};
      result.status = ajax.status;
      result.response = ajax.responseText;
 
      updatePage(result.status, result.response);
      if (callback) callback(result);
  }
}
 
function updatePage(status, response)
{
   document.getElementById("status").innerHTML=status;
   document.getElementById("response").value=response;
}
 
</script>
</head>
 
<body>

  <h1>Test SM RestfulAPI</h1>

  Request: <textarea id="request" width="80" height="60"></textarea>

  <p></p>

  Status: <p id="status"></p>

  Response: <textarea id="response" width="80" height="60"></textarea>

  <script language="javascript">


// Defaults

    var method = "GET"
    var request = null;
    var contenttype = null;
    var sync = false;


// Credentials

    var user = "falcon";

    var password = "";


// TEST

    var method = "DELETE";

    var URL = "http://localhost:13080/SM/9/rest/incidents/IM10001/attachments/58ac7b3200242211802b29a8";


    sendrequest(method, URL, contenttype, user, password, sync, request);


  </script>

</body>

</html>