Purpose of project

Jraml helps you build your java implementation of REST API, based on specification, described by raml file.

Easy to use

Connect a library

...
        <dependency>
            <groupId>com.github.hammelion</groupId>
            <artifactId>jraml</artifactId>
            <version>0.3</version>
        </dependency>
...

Add listener to your servlet container configuration (web.xml)

...
    <listener>
        <listener-class>com.github.hammelion.JRamlBootstrap</listener-class>
    </listener>
...

Annotate your resources with @RAMLConfig annotation

...
@RAMLConfig("conf/raml/api.raml")
public class TestResource {
...

api.raml should be on resources classpath

How it works

To ensure, that your java implementation reflects your RAML specification, use Jraml. It helps you keep your RAML specification and java implementation in sync.

You can generate your first REST API implementation using RAML for JAX-RS.

Jraml reads RAML file and annotates your java classes with JAX-RS annotations in runtime, if needed. You can then use any JAX-RS implementation (Jersey, RestEASY, Restlet, etc.) with your @RAMLConfig-annotated REST resources.

Naming conventions

In order to map RAML structure to java code you should name your classes, methods and parameters according to the following convention:

Class name

A java class represents a specific RAML Resource. That is why the class name should end with Resource. E.g.:

To define REST URL /test we specify it in RAML file:

/testResource:

By using JAX-RS we would annotate our java code as follows:

@Path("/test")
public class AnyClassName {

And with JRAML the code transforms into:

public class TestResource

Method name

A java method represents a specific action on RAML Resource. That is why the method name should start with action name. E.g.:

GET

To define GET on /test URL we specify it in RAML file:

/testResource:
  get:

By using JAX-RS we would annotate our java code as follows:

@Path("/test")
public class AnyClassName {
...
@GET
public ReturnType methodName() {

And with JRAML the code transforms into:

public class TestResource
...
public ReturnType getAnyMethodName()

POST

To define POST on /test URL we specify it in RAML file:

/testResource:
  post:

By using JAX-RS we would annotate our java code as follows:

@Path("/test")
public class AnyClassName {
...
@POST
public ReturnType methodName() {

And with JRAML the code transforms into:

public class TestResource
...
public ReturnType postAnyMethodName()

PUT

To define PUT on /test URL we specify it in RAML file:

/testResource:
  put:

By using JAX-RS we would annotate our java code as follows:

@Path("/test")
public class AnyClassName {
...
@PUT
public ReturnType methodName() {

And with JRAML the code transforms into:

public class TestResource
...
public ReturnType putAnyMethodName()

DELETE

To define DELETE on /test URL we specify it in RAML file:

/testResource:
  delete:

By using JAX-RS we would annotate our java code as follows:

@Path("/test")
public class AnyClassName {
...
@DELETE
public ReturnType methodName() {

And with JRAML the code transforms into:

public class TestResource
...
public ReturnType deleteAnyMethodName()

Method parameters

It is a very good idea to ensure typization in your java REST API. You should do it by wrapping REST parameters in immutable POJOs:

public final class MyParameter
{
   private final String value;

   public MyParameter(final String value)
   {
      this.value = value;
   }

   public String getValue()
   {
      return this.value;
   }

   @Override
   public String toString()
   {
      return this.value;
   }
}

Now it is very easy to map REST parameters to your java implementation:

Query parameters

To define GET on /test URL with query parameters we specify it in RAML file:

/testResource:
  get:
    queryParameters:
        myParameter:
          type: string

By using JAX-RS we would annotate our java code as follows:

@Path("/test")
public class AnyClassName {
...
@GET
public ReturnType methodName(MyParameter anyParameterName) {

And with JRAML the code transforms into:

public class TestResource
...
public ReturnType getAnyMethodName(MyParameter anyParameterName)

Useful links

RAML Website | JAX-RS | RAML for JAX-RS