The document provides a specification for an email attachment retrieval API that allows third party solutions to retrieve email attachment raw contents from an IMS server. The API defines a simple HTTP(s) request that third parties can make to the IMS server to retrieve an attachment, including parameters for a request ID, file ID, and security blob. The response will return the attachment content and standard HTTP status codes to indicate success or errors.

1. DESIGN SPEC 1 (4)
S&S-CCC Attachment Retrieval API
Oliver Yuan 07/17/08
Email Attachment Retrieval API
Specification
Owner: Oliver Yuan
Originator: Oliver Yuan
Status: Draft
Document ID:
Change History
Issue Date Handles by Comments
0.0.1 07.17.2008 Oliver Yuan Initial draft

2. DESIGN SPEC 2 (4)
S&S-CCC Attachment Retrieval API
Oliver Yuan 07/17/08
TABLE OF CONTENTS
1. INTRODUCTION ...................................................................................................................................................................3
1.1 ABOUT THIS DOCUMENT....................................................................................................................................................3
2. API DESCRIPTION ...............................................................................................................................................................3
2.1 REQUEST FROM CLIENT .....................................................................................................................................................3
2.2 RESPONSE FROM IMS SERVER ..........................................................................................................................................3

3. DESIGN SPEC 3 (4)
S&S-CCC Attachment Retrieval API
Oliver Yuan 07/17/08
1. INTRODUCTION
1.1 About this document
The document specifies the NIMS Email Attachment Retrieval API for third party solution.
2. API DESCRIPTION
IMS defines an API for 3rd party solution to retrieve email attachment raw contents from IMS server. To
serve the purpose without compromising IMS server performance a simple HTTP(s) based API backed
by servlet is defined.
2.1 Request from client
To retrieve an email attachment from an IMS cluster, client can simply issue an http request as defined
below:
Http(s)://[ims server name]/admin/fetchAttachment.do?reqID=1&fileID=90EF&securityBlob=ABCDEF
Parameter definitions:
Name Type Meaning
reqID String for hexadecimal This parameter should be the one either contained
values of representing in an earlier service request from IMS to the 3rd
16-byte byte array party solution (client) or a new one client generates.
fileID String for hexadecimal This parameter is a hash code for a binary blob,
values of representing which is the whole content for a file in this case.
16-byte byte array
This parameter should be contained in an earlier
service request from IMS to the 3rd party solution
(client) or a new one the client. Client must provide
fileID in such way that IMS must be able to use this
parameter to identify the email attachment.
securityBlob string for hexadecimal IMS uses the security blob to authenticate the
values of a byte array connection from the client as well as validate the
of variable length request. There must be some mutual agreement on
security blob generation between IMS and client.
2.2 Response from IMS server
Response from IMS server is typical http response. Response header contains status code and if status
code is 200 it will also contain content length and content type (application/octet-stream). The response
body is attachment file raw content. The following table lists possible status code from response:
Status code Meaning
200 A request has been successfully handled and response contains
file contents
400 The request contains bad syntax.

4. DESIGN SPEC 4 (4)
S&S-CCC Attachment Retrieval API
Oliver Yuan 07/17/08
401 Failed to authenticate (security blob is wrong)
404 Request not found or timed out
406 Attachment File not found or general IO exception when reading
attachment file from the system
500 Internal server error, for example server throws exceptions when
handling request
503 Service is not available