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
 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
 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.

 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