Jax-RS API POST and GET methods (RESTful Services)

Question

I have a project (homework) about JAX-RS. I'm working with NetBeans, Jersey and Tomcat. In the post method for example: '{"user":{"username":"accavdar", "gender":"M", "birthDate":"06.11.1982"}}' when such a request comes I have to parse this input and add new user to my system. The sample response must be:

{
    "meta": {
        "code": 200
    },
    "data": {
        "message": "You successfully created a user."
    }
}

Expectable error can be like that:

{
    "meta": {
        "code": 101,
        "type": "FieldError",
        "errors": [
            {
                "fieldName": "fullname",
                "rejectedValue": null
            }
        ]
    }
}

Another problem is that: With using Get method the develepor can want to list all user in the system. The response must be like that :

{
  "meta": {
    "code": 200
  },
  "data": [
    {
      "id": 1,
      "username": "sample",
      "fullname": "sample",
      "gender": "M",
      "birthDate": "12.02.1990"
    },
    {
      "id": 2,
      "username": "sample",
      "fullname": "sample",
      "gender": "M",
      "birthDate": "21.09.1940"
    }
  ]
}

I want to keep users in a text file, there is no limitation about the way of keeping users.(You can keep in database or in memory) But I have no idea about how to handle request input and generate a response like that. I don't want you to do my homework but could anyone give tips about my problem, please?

NOTE: We will work only with JSON "Content-Type: application/json" "Accept: application/json"

EDİT: #Bogdan , Thank you very much for your answer. I searched the web sites you gave. I want to learn that how is that output produced?:

{
    "meta": {
        "code": 200
    },
    "data": {
        "message": "You successfully created a user."
    }
}

or

{
  "meta": {
    "code": 200
  },
  "data": {
    "id": 1,
    "username": "jack",
    "fullname": "jack",
    "gender": "M",
    "birthDate": "12.12.2012"
  }
}

I have "meta" and "user" classes.

@XmlRootElement(name="data")
public class User {

    @XmlElement
    public int id ;
    @XmlElement
    public String username;
    @XmlElement
    public String fullname;
    @XmlElement
    public String gender;
    @XmlElement
    public String birthDate;

    public User(){

    }

@XmlRootElement(name="meta")
public class Meta {

    @XmlElement
    int code=200;

    public Meta(){

    }

Also I have this jaxbcontextresolver class

@Provider
public class JAXBContextResolver implements ContextResolver<JAXBContext>{

    private JAXBContext context;
    private Class[] types = {User.class, Meta.class};


    public JAXBContextResolver() throws Exception {

        this.context = 
        new JSONJAXBContext(  JSONConfiguration.mapped().nonStrings("id").nonStrings("code").build(), types); 
    }

    @Override
    public JAXBContext getContext(Class<?> objectType) {
         for (Class type : types) {
             if (type == objectType) {
                 return context;
             }
         }

        return null;

    }

}

but how to create this response constructs, could any help me?

Answer 1

Your application works with users. This is the resource that you application deals with and your client interacts with for creating, updating, deleting and getting (basically CRUD).

But a user is an abstract resource so your server and client interact with each other by using representations of this resource. The representations can be in JSON format (as in your example), XML etc. Your client specifies what type of representation it wants and the server specifies the representation type it returns by means of the Content-Type. The body of the request/response matches the content type.

This is a Java application so in your application code the users are represented as Java objects. You need to transform the request/response body into objects with getters and setters. You can use JAXB to do the XML transformation, and with a library like Jackson you can transform JSON. You can off course do it manually and parse strings into objects and output strings from objects but that would be more work.

A client submits JSON and after transformation you will have your Java objects that you can handle. You can keep them in memory inside an application scope map or write them inside a file or database and change their representation once again.

Your application will bind URLs to specific actions that transform the request representation into objects, perform operations on the objects then return them to be transformed again into the representation the client expects.

The above are just basic explanations. All your questions can be answered if you follow some JAX-RS tutorials (e.g. a quick search returns REST with Java (JAX-RS) using Jersey - Tutorial or REST: CRUD with JAX-RS (Jersey). I'm sure there are lots other). Your question is too open ended so just dig in and return with specific questions on stackoverflow when you hit road blocks.

EDIT : seems you are struggling with this a little so I'll add a basic service to get you started, let's say for the list of users.

You didn't mention so far nothing about your service class. That's the important one, something like:

package com.test;

import java.util.ArrayList;
import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/api")
public class Test {

    @GET
    @Path("/users")
    @Produces({ MediaType.APPLICATION_JSON })
    public UsersResponseWrapper getUsers() {
        List<User> users = new ArrayList<User>();

        User u1 = new User();
        u1.setId(1);
        u1.setFullname("Joe Doe");
        u1.setGender("M");
        u1.setUsername("joe.doe");
        u1.setBirthDate("1919-12-12");

        User u2 = new User();
        u2.setId(1);
        u2.setFullname("John Smith");
        u2.setGender("M");
        u2.setUsername("john.smith");
        u2.setBirthDate("1990-01-01");

        users.add(u1);
        users.add(u2);

        UsersResponseWrapper resp = new UsersResponseWrapper();
        resp.setMeta(new Meta(200));
        resp.setData(users);

        return resp;
    }
}

Then your user and meta classes:

package com.test;

public class Meta {
    private int code;

    public Meta(int code) {
        this.code = code;
    }

    public Meta() {
        this.code = 200;
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }
}

package com.test;

public class User {
    private int id;
    private String username;
    private String fullname;
    private String gender;
    private String birthDate;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getFullname() {
        return fullname;
    }

    public void setFullname(String fullname) {
        this.fullname = fullname;
    }

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    public String getBirthDate() {
        return birthDate;
    }

    public void setBirthDate(String birthDate) {
        this.birthDate = birthDate;
    }

}

A JAXB provider:

package com.test;

import java.util.ArrayList;

import javax.ws.rs.ext.ContextResolver;
import javax.ws.rs.ext.Provider;
import javax.xml.bind.JAXBContext;

@Provider
public class JAXBContextResolver implements ContextResolver<JAXBContext> {
    private JAXBContext context;
    private static Class<?>[] types = {UsersResponseWrapper.class, User.class, Meta.class, ArrayList.class};

    public JAXBContextResolver() throws Exception {
        this.context = JAXBContext.newInstance(types);
    }

    @Override
    public JAXBContext getContext(Class<?> objectType) {
         for (Class<?> type : types) {
             if (type == objectType) {
                 return context;
             }
         }
        return null;
    }
}

Something from web.xml:

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
      version="3.0">
 <servlet>
    <servlet-name>RestService</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
      <param-name>com.sun.jersey.config.property.packages</param-name>
      <param-value>com.test</param-value>
    </init-param>
  </servlet>
  <servlet-mapping>
    <servlet-name>RestService</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

And a wrapper for your result:

package com.test;

import java.util.List;

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class UsersResponseWrapper {
    private Meta meta;
    private List<User> data;

    public Meta getMeta() {
        return meta;
    }

    public void setMeta(Meta meta) {
        this.meta = meta;
    }

    public List<User> getData() {
        return data;
    }

    public void setData(List<User> data) {
        this.data = data;
    }
}

I think this last class is what put you in difficulty since your result is formed of both meta content and data content. Remember you need to return objects (the default Jackson mapper from Jersey distribution will then take care of it) and it happens you have a complex one. The above should return this (formatting not included):

{
    "data": [
        {
            "birthDate": "1919-12-12",
            "fullname": "Joe Doe",
            "gender": "M",
            "id": "1",
            "username": "joe.doe"
        },
        {
            "birthDate": "1990-01-01",
            "fullname": "John Smith",
            "gender": "M",
            "id": "1",
            "username": "john.smith"
        }
    ],
    "meta": {
        "code": "200"
    }
}

That's about as much I can add to this as details. It's your homework after all :). You are doing fine, just keep going.