使用JSON参数简化REST URL

Question

I have been assigned a task and I really don't know how to even begin solving it, so any help would be appreciated. Consider the following example:

@Path("/v1/{server}:{port}/instance")  
public class WSInstance {
        private static final Log        log = LogFactory.getLog(WSInstance.class);

        private final String    PLANNING_PROPNAME = "**PLNG_NAME**";
        private final String    PLANNING_PROPVAL = "**CALENDAR_NAME**";

        @GET
        @Path("/{instanceName}")
        @Produces("text/plain")
        public String getInstanceStatus(@Context HttpHeaders headers, 
                @PathParam("server")String server, 
                @PathParam("port")int port,
                @PathParam("instanceName") String instName,
                @DefaultValue("") @QueryParam("date") String date,
                @DefaultValue("") @QueryParam("instnum") String numexec)
        {
            return getInstanceStatus(Utils.extractUserInfo(headers), server, port, instName, numexec, date);    
        }

An example of a call to the aforementioned method is going to look like this:

/v1/serverName:portNumber/instance/toto?date=21090207&instnum=0000

What the task is asking is to replace all the variables in that url ( serverName , portNumber , toto , date and instnum ) with json parameters. This is meant to simplify the REST URL.

Any idea where to begin?

---

** EDIT : Thanks to everyone for their answers, you've certainly helped me a lot. Here's what I have done so far:

I decided to take a "simpler" class and method to familiarize myself with the procedure. So I took this one:

@Path("/v2/{server}:{port}/admin/")
public class WSAdmin {
    private static final Log log    = LogFactory.getLog(WSAdmin.class);

    @PUT
    @Path("/device")
    @Produces("text/plain")
    @Consumes("application/json")
    public String putDevice(String jsonObject, @Context HttpHeaders headers,
                                    @PathParam("server")String server,
                                    @PathParam("port")int port)
    {
        ObjectMapper mapper = new ObjectMapper();

        try
        {
            return updateDevice(mapper.readTree(jsonObject), Utils.extractUserInfo(headers), server, port);
        }
        catch (JsonProcessingException e)
        {
            return e.getMessage();
        }
        catch (IOException e)
        {
            return e.getMessage();
        }
    }

I changed it like this:

@Path("/v2/admin/")
public class WSAdmin {
    private static final Log log    = LogFactory.getLog(WSAdmin.class);

    @POST
    @Path("/device")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response putDevice(Admin admin)
    {
            String output = admin.toString();
            return Response.status(200).entity(output).build();
    }

Then I created the corresponding POJO:

@XmlRootElement
public class Admin {

    private String server;
    private int port;
    private Date date;
    private String instnum;

// Constructors + getters + setters

    @Override
    public String toString() {
        return new StringBuffer("Server: ").append(this.server)
                .append("Port: ").append(this.port).append("Date: ")
                .append(this.date).append("InstNum: ")
                .append(this.instnum).toString();
    }
}

Then I edited the web.xml file to be able marshal and unmarshal Java Objets:

<init-param>
    <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
    <param-value>true</param-value>
</init-param>

But for some reason, i'm getting the following error when I make the call from postman:

GRAVE [http-nio-8080-exec-5] com.sun.jersey.spi.container.ContainerRequest.getEntity A message body reader for Java class com.ws.v3.models.Admin, and Java type class com.ws.v3.models.Admin, and MIME media type application/json was not found.
The registered message body readers compatible with the MIME media type are:
application/json ->
  com.sun.jersey.json.impl.provider.entity.JSONJAXBElementProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONRootElementProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONListElementProvider$App
*/* ->
  com.sun.jersey.core.impl.provider.entity.FormProvider
  com.sun.jersey.core.impl.provider.entity.StringProvider
  com.sun.jersey.core.impl.provider.entity.ByteArrayProvider
  com.sun.jersey.core.impl.provider.entity.FileProvider
  com.sun.jersey.core.impl.provider.entity.InputStreamProvider
  com.sun.jersey.core.impl.provider.entity.DataSourceProvider
  com.sun.jersey.core.impl.provider.entity.XMLJAXBElementProvider$General
  com.sun.jersey.core.impl.provider.entity.ReaderProvider
  com.sun.jersey.core.impl.provider.entity.DocumentProvider
  com.sun.jersey.core.impl.provider.entity.SourceProvider$StreamSourceReader
  com.sun.jersey.core.impl.provider.entity.SourceProvider$SAXSourceReader
  com.sun.jersey.core.impl.provider.entity.SourceProvider$DOMSourceReader
  com.sun.jersey.json.impl.provider.entity.JSONJAXBElementProvider$General
  com.sun.jersey.core.impl.provider.entity.XMLRootElementProvider$General
  com.sun.jersey.core.impl.provider.entity.XMLListElementProvider$General
  com.sun.jersey.core.impl.provider.entity.XMLRootObjectProvider$General
  com.sun.jersey.core.impl.provider.entity.EntityHolderReader
  com.sun.jersey.json.impl.provider.entity.JSONRootElementProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONListElementProvider$General

Those who had a similar error got it to disappear by adding either gerson or jersey-json in pom.xml. I've added them but the problem didn't get fixed.

Any idea?

Answer 1

Probably you have to change the method type to POST and pass the data as json in the body of the request.

The GET request

GET /v1/yourServerName:8080/instance/toto?date=21090207&instnum=0000

can become the following POST request

POST /v1/instance
{
  "serverName":"yourServerName",
  "portNumber":8080,
  "date":21090207,
  "instnum":"0000"
}

Note that instnum is not a numeric field because you passed the string 0000 that can't be represented as a numeric value. Instead portNumber and date can be numeric values.

Answer 2

Consider using Jackson. Jackson maps JSON <-> objects. Read about how you can use it with Jersey (REST) here: https://www.mkyong.com/webservices/jax-rs/json-example-with-jersey-jackson/

Answer 3

Per specification the payload of a GET request is undefined. You should, therfore, refrain from sending a body with a GET request. As Davide already suggested you should switch to POST here instead, as here the semantics of a payload received are defined by you, the server/API maintainer.

However, as you've tagged your post with rest you should probably consider copying the concepts used in the Web for over 2 decades now and translate it to your API design. First, REST architecture don't care about the structure of your URI. The URI itself is just a pointer to a resource and clients shouldn't need to interpret it nor hack it. All the information needed for a client to make distinctive choices should be provided by the server to start with. As clients shouldn't parse and interpret URIs how do they determine whether a URI is of use for the client or not?

Well, how do we humans interact with URIs in web-pages? Usually they are annotated with human readable text that summarizes the content of that link (as with the specification ie above). Such short but meaningful names are usually called link-relation names and should be "attachted" to each URI. A client reading such link-relation names and just invoke the accompanying URI will be able to continue its task if the server ever has the need to change its URI structure. This is one important step towards decoupling clients from servers. Such link relation names should be standardized but may also be specified in common knowlege or specified in media-types itself.

A common mistake many so called "REST APIs" do is to support either application/xml and/or application/json only. Those are very poor media types in a REST architecture as they only define the syntax to use but not the semantics of the respective elements. It is thus hard for a client to determine the intent of such a document and to easy to fall into the typed resource trap and assume that a certain resource has a certain type. If such a (non-standardized) representation changes, chances are high that a client will break to interoperate with that service/API further.

Media types are more or less standardized processing-rules for a certain received payload that should help give the receiver some meaning of the content and what it might do with it. One probably well known media type is HTML which defines when certain elements are feasible and the constraint each element has. It also defines how certain elements are rendered and how it is backward compatible with former versions. It is the defacto standard when it comes to support for links and link-relations. While HAL , Collection+JSON , ... are steps into the right direction in terms of support of links and relation names, they are far from providing the same semantics as HTML does, though they should be preferable to plain JSON as they not only specify a syntax but also semantics of certain elements such as _links ie which help the client to differentiate links from content.

Media types are especially important in terms of content-type negotiation where a client requests a server to return a representation format a client understands. If the server is not able to produce such a representation it will inform the client with an expressive enough error code (406). If the server is not able to process the media type provided by the client (on a POST, PUT, PATCH, ... operation) it will also inform the client that it does not understand such a format (415).

A general advice on designing REST APIs would be to think of the API in terms of a Web server and also desing the whole interaction with it like that. Ie if a client has to perform certian input it should not send just a playin JSON document with some random fields (specified in some external documentation) to the server, but the server should teach the client on how to send such a request to start with. Similar to Web forms where humans should enter text and stuff, REST APIs should return a media-type representing a formular that teaches a client what fields the server expects, which operation to use and the target to send the payload to.

In regards to the actual question, I'm not sure why your employee is so keen on removing parameters from the URI. As mentioned in my first paragraph on sending a payload you'd need to switch to POST and therefore automatically loose the guaranteed safe and idempotent features of the GET operation, besides not being cacheable by default.

What you can do ie is allow users or your coworkers to preconfigure certain queries and create short/tiny URLs for these preconfigured URIs. Here you should provide a form-like media type to the client where it can select the options to choose from and enter further necessary data. Once you received such a request you store such a preconfiguration and return a short/tiny URL for that preconfiguration in the Location header of the response. You should also add the preconfigured links in the regular response so that a client is able to invoke it if it didn't store it right after persistence. By doing so you still have the benefits of the GET operation while having the flexibility to add new or customize existing queries on the fly. As mentioned before, a client won't be able to make much use of such links in a plain application/json representation. If the client supports application/hal+json it might at least know what link-relation and links are and therefore be able to lookup and invoke the URI via its accompanying link relation name. This basically gives you the freedom to later on change the URI structure if needed without affecting the client.