Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Background

Mime messages are text, encoded and wrapped up for transmission.  JEMH uses this format for audit history and test cases, it should also expose a REST API for external tools to drive JEMH via REST:

Code Block
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@localhost>
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8

some text


Required Info

In order for JEMH to process a mail, it needs to use a Profile.  Until now Profiles are tied to mailboxes, allowing arbitrary external use of those profiles may trigger unexpected scenarios, therefore:

  • Profiles will need to explicitly opt-in to API use

    Image RemovedImage Added
  • Lists of profiles via REST will only show those that have opted-in.

  • All REST API's require an authenticated user

API

URLS must follow this pattern

  • create POST /urlOfRestResource

  • read GET /urlOfRestResource[/id]

  • update PUT /urlOfRestResource/id

  • delete DELETE /urlOfRestResource/id

URL

Method

Response

.../rest/jemh/latest/public/profile/list

GET

List of JSON profile objects that identify Profile NAME and ID.

Requires authenticated user (base 64 headers?)

Request:

Code Block
curl -D- -u admin:admin -X GET http://dev-jira:8080/rest/jemh/latest/public/profile/list

Response:

Code Block
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-AREQUESTID: 717x157x1
X-ASEN: SEN-2050663
Set-Cookie: JSESSIONID=54EBDC61B68527A9C48C9106A76054E0; Path=/; HttpOnly
X-Seraph-LoginReason: OK
Set-Cookie: atlassian.xsrf.token=B3QZ-T2ZD-68A2-PNV6|c01f148e72fd5ea6a08f5a62276e077754c7005a|lin; Path=/
X-ASESSIONID: 1c9uhsa
X-AUSERNAME: admin
Cache-Control: no-cache, no-store, no-transform
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 24 Sep 2014 10:57:58 GMT
[{"id":1,"name":"Testing","desc":"TEST"}]


/rest/jemh/latest/public/mailbox/deliver

POST

Request

Using an email like:

Code Block
MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@localhost>
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8
some text

A CURL command would be of format (NOTE: initially application/x-www-form-urlencoded was supported, since 1.6.15, multipart/form-data is also supported):

Code Block
curl -v -u admin:admin -H "Content-Type: multipart/form-data" --data "profileId=1&email=...." -X POST http://dev-jira:8080/rest/jemh/latest/public/mailbox/deliver

URLEncoding the content (shown above) eg through services like http://www.url-encode-decode.com/ and replacing .... with the result:

Code Block
curl -v -u admin:admin -H "Content-Type: multipart/form-data" --data "profileId=1&email=MIME-Version%3A+1.0%0AReceived%3A+by+10.223.112.12+with+HTTP%3B+Sat%2C+18+Jun+2011+22%3A42%3A26+-0700+%28PDT%29%0ADate%3A+Sun%2C+19+Jun+2011+17%3A42%3A26+%2B1200%0AMessage-ID%3A+%3CBANLkTinB1mfSh%2BGwOXGNWoL4SyDvOpdBoQ%40mail.gmail.com%3E%0ASubject%3A+This+is+a+starting+email+template%2C+update+as+required%0AFrom%3A+%22Andy+Brook%22+%3Candy%40localhost%3E%0ATo%3A+changeme%40thiswontwork.com%0AContent-Type%3A+text%2Fplain%3B+charset%3DUTF-8%0A%0Asome+text" -X POST http://dev-jira:8080/rest/jemh/latest/public/mailbox/deliver

RESPONSE format:

Code Block
{ 
createdIssues [] {id,key,self},
updatedIssues [] {id,key,self},
commentedIssues [] {id,key,self},
filterResult {name, action, reason},
hints [] {hintText, causedRejection, providedValue, validValues}
error,
detail,
processingException,
isForwarded,
processTime,
processOutcome
}

Example Response:

Code Block
{"createdIssues":[{"id":15910,"key":"TEST-29","self":"http://dev-jira:8080/rest/api/2/issue/15910"}],"processTime":651,"processOutcome":"canHandle","forwarded":false}



Worked JAVA Examples

Example Test Case
Code Block
languagejava
package com.javahollic.jira.emh.publicapi;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLConnection;
import org.apache.commons.codec.binary.Base64;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.io.IOUtils;
import org.junit.Assert;
import org.junit.Test;
public class TestPost
{
	@Test
	public void testPost() throws IOException
	{
		InputStream is = getClass().getClassLoader().getResourceAsStream("plaintextEmail.txt");
		Assert.assertNotNull(is);
		String emailStr=IOUtils.toString(is,"UTF-8");
				
		String name = "admin";
		String password = "admin";
		String authString = name + ":" + password;
		System.out.println("auth string: " + authString);
		byte[] authEncBytes = Base64.encodeBase64(authString.getBytes());
		String authStringEnc = new String(authEncBytes);
		System.out.println("Base64 encoded auth string: " + authStringEnc);
		HttpClient client = new HttpClient();
		client.getParams().setParameter("http.useragent", "Test Client");
		BufferedReader br = null;
		PostMethod method = new PostMethod("http://dev-jira:8080/rest/jemh/latest/public/mailbox/deliver");
		method.addParameter("profileId", "1");
		method.addParameter("email", emailStr);
		method.addRequestHeader("Authorization", "Basic " + authStringEnc);
		try
		{
			int returnCode = client.executeMethod(method);
			if (returnCode == HttpStatus.SC_NOT_IMPLEMENTED)
			{
				System.err.println("The Post method is not implemented by this URI");
				// still consume the response body
				System.err.println("\n"+method.getResponseBodyAsString());
			}
			else
			{
				String response=IOUtils.toString(method.getResponseBodyAsStream());
				System.out.println("\n-------------------------\n"+response+"\n-------------------------\n");
			}
		}
		catch (Exception e)
		{
			System.err.println(e);
		}
		finally
		{
			method.releaseConnection();
			if (br != null)
				try
				{
					br.close();
				}
				catch (Exception fe)
				{
				}
		}
	}
	@Test
	public void testGet()
	{
		try
		{
			String webPage = "http://dev-jira:8080/rest/jemh/latest/public/profile/list";
			String name = "admin";
			String password = "admin";
			String authString = name + ":" + password;
			System.out.println("auth string: " + authString);
			byte[] authEncBytes = Base64.encodeBase64(authString.getBytes());
			String authStringEnc = new String(authEncBytes);
			System.out.println("Base64 encoded auth string: " + authStringEnc);
			URL url = new URL(webPage);
			URLConnection urlConnection = url.openConnection();
			urlConnection.setRequestProperty("Authorization", "Basic " + authStringEnc);
			InputStream is = urlConnection.getInputStream();
			InputStreamReader isr = new InputStreamReader(is);
			int numCharsRead;
			char[] charArray = new char[1024];
			StringBuffer sb = new StringBuffer();
			while ((numCharsRead = isr.read(charArray)) > 0)
			{
				sb.append(charArray, 0, numCharsRead);
			}
			String result = sb.toString();
			System.out.println("*** BEGIN ***");
			System.out.println(result);
			System.out.println("*** END ***");
		}
		catch (MalformedURLException e)
		{
			e.printStackTrace();
		}
		catch (IOException e)
		{
			e.printStackTrace();
		}
	}
}
 

Related articles

Filter by label (Content by label)
showLabelsfalse
max5
spacesJEMH
showSpacefalse
sortmodified
typepage
reversetrue
labelsevent listener jemh issue notification
cqllabel in ( "rest" , "java" , "jira" , "issue-creation" ) and space = "JEMH"
Page Properties
hiddentrue


Related issues