Stardust/Knowledge Base/Web Service API/Exposing REST Service

Requirements

• Exposing service as REST service

How to Do

• This article illustrates how to create REST service and expose it.
• This article uses example to create REST to add notes to specific process instance.
• Below are the steps to create REST.

• 1. Create REST class to implement REST service.
• 2. Define this REST bean as jaxrs service bean.
• 3. Deployment

Creating REST Class:

• Create new class which you need to expose as REST service.
• Here we create service class as NotesRestlet. Specify REST path to identify this service.

@Path("/processes/notes")
public class NotesRestlet {
………
}

• Inside this class, create REST method by specifying below:

• • HTTP Method type(GET/PUT/POST/DELETE)
• • MIME media types of representations a resource can consume that were sent by the client.
• • MIME media types of representations a resource can produce and send back to the client
• • Relative URI path to be exposed.

	@POST
	@Consumes(MediaType.APPLICATION_JSON)
	@Produces(MediaType.APPLICATION_JSON)
	@Path("addNote")
	public Response addNotes(@QueryParam("processInstanceOID") String processInstanceOID, 
			@QueryParam("stardust-bpm-partition") String partition, String notesData)

• In above example, addNotes method is exposed as HTTP POST request. A JSON object is used to send and receive from/to client in a request and response. notesData is string representation of JSON object. processInstanceOID and stardust-bpm-partition are request parameters. You can have your own implementation in this method.

• If you need ServiceFactory instance in your implementation, you will need partition in order to work in a multi-tenant environment. Hence partition is passed as request parameter.

You can fetch ServiceFactory instance using below.

	Map <String, String> prop = new HashMap<String, String>();
	prop.put(SecurityProperties.PARTITION, this.partition);
	ServiceFactory serviceFactory =   ServiceFactoryLocator.get(backdoorAccount, backdoorKey, prop);

• Here this.partition is the partition sent as request parameter. backdoorAccount and backdoorKey are the REST class members injected while defining bean.

Defining REST bean as jaxrs service bean:

• Create context file under resources folder and define this bean as jaxrs bean.

	<jaxrs:server id="stardust" address="/stardust">
		<jaxrs:serviceBeans>
			<ref bean="notesRestletBean" />
		</jaxrs:serviceBeans>
	</jaxrs:server>
 
	<bean id="notesRestletBean"
class="org.eclipse.stardust.engine.rest.NotesRestlet" scope="prototype">
<property name="backdoorAccount" value="${Security.Authentication.MasterAccount}" />
<property name="backdoorKey" value="${Security.Authentication.MasterKey}" />
	</bean>

• Here while defining notesRestletBean, backdoorAccount and backdoorKey are getting fetched from carnot.properties. Define this bean as jaxrs bean by providing id and address for it.

• Note: You should use unique id for each REST.

Deployment:

• Once you are ready with your REST class and its declaration, it is the time to build your jar and deploy in your web container. Once your server is up, you can check if your REST service is exposed correctly using,

http://localhost:8081/dogfood/services/rest/stardust/processes/notes/addNote?_wadl

You are ready with your REST and can call it using

http://localhost:8081/dogfood/services/rest/stardust/processes/notes/addNote?processInstanceOID=4939&stardust-bpm-partition=default