If you are a newbie to REST...

Last couple of months, I was working on implementing a REST interface to one of our java API. Here I would like to share some of my experiences I came across on that process. Being a total newbie, I had to do a lot of readings before start implementing the REST service.

As all of you aware, REST is a style of software architecture. So everything depends on how you design your resource objects. In our case, I need to come up with a REST interface for existing registry API. In registry API, what we basically deal with back-end database. It has a data structure which we design according to what kind of data will be present in a science gateway. Here is our data structure.

gateway *
  |- descriptors *
  |- published workflows *
  |- gateway-worker *
  |       |- workspace

  |       |      |- workflows
  |       |      |- projects *
  |       |             |- experiments *
  |       |                  
  |
  |
  |
  |
  |- name
  |- owner
  |
  |

users

So in the Registry API, we have lot of methods to facilitate this data structure. Basically we have several interfaces for each and every basic models. 

• ConfigurationRegistry
• DescriptorRegistry
• ProjectRegistry
• ProvenanceRegistry
• UserWorkflowRegistry
• PublishedWorkflowRegistry

So I need to come up with a REST interface for all the methods exposed by above interfaces. 

There are several problems that I need to find solutions before start implementing the REST service.

• Java interface is written without intention of using them in a REST interface in the future. Due to that most of the objects that are returned and taking as parameters are complex types which are not possible to serialize in to an XML. So I have to make those objects simple and annotated. Example class would be look like this.

  @XmlRootElement
  @XmlAccessorType(XmlAccessType.FIELD)
  public class WorkflowInstance {
  
      public WorkflowInstance() {
      }
  }
  

• In a Java API,  you can have overloaded methods. But in a REST API, you can not have two methods with the same name. 
• You should only expose that are useful for an outside user. In tha Java API, there are lot of intermediate methods. Those methods should not be exposed.   
• What is the best REST framework that we should use. There are several options you can try. Some are Jersey, Restlet, RESTEasy, Apache CXF, Apache Wink etc. They all have their pros and cons. Before selecting a framework, there are several things you need to consider.  
• Whether they have both server and client support 
• Whether they have custom annotations other than basic REST annotations
• How easy, it is to integrate (whether it is too bulky )
• Whether the REST framework license compatible with the license of your software

So in summary, if you are planning to have a REST interface, you should have your Java APIs as much as simple you can. They should not contain complex object types. And also you should make sure that the associations between the objects should not create cyclic dependencies among them.