Dissecting our first REST service

Understanding REST

REST - Representational State Transfer
WS - Web Service
RS - RESTful service
javax.ws.rs - java API for RESTful services

We are starting off with the following code, running on http://localhost:8080/unh/rest/myresource

package test;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
 
@Path("myresource")
public class Sandbox {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getIt() {
        return "Something else";
    }
}

If you are running your code on the Tomcat within your Eclipse, whenever you make a change, your Tomcat should reload yourself, so refreshing the web browser page should reflect your changes, Start with modifying the return string to a different value.

See the change? Good.

Now, modify the @Path("myresource") to, say @Path("myrest") - guess where the change will be reflected?

Correct, in the URL path, now you can access your resource at http://localhost:8080/unh/rest/myrest

You can pass parameters to your web service through a URL:

package test;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
 
@Path("sandbox/{username}")
public class Sandbox {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getIt(@PathParam("username") String userName) {
        return "Hello "+userName;
    }
}

Now access the URL: http://localhost:8080/unh/rest/sandbox/Gula

You should see:

Hello Gula

Accessing http://localhost:8080/unh/rest/sandbox/123 should say

Hello 123

A regular expression can be passed to the Path annotation, ex:

@Path("sandbox/{username:[A-z]*}")

Now, the http://localhost:8080/unh/rest/sandbox/123 would return an HTTP 404 error, while the http://localhost:8080/unh/rest/sandbox/Gula will still work

package test;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
 
@Path("sandbox/{username:[A-z]*}")
public class Sandbox {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("sayhello")
    public String getIt(@PathParam("username") String userName) {
        return "Hello "+userName;
    }
}

Now the same behavior will reside at http://localhost:8080/unh/rest/sandbox/Gula/sayhello

TRY YOURSELF:
Modify your code such that the method we wrote resides at http://localhost:8080/unh/rest/sandbox/sayhello/Gula

CRUD operations:

C - Create
R - Read
U - Update
D - Delete



Operation
SQL
HTTP
DDS


Create
INSERT
PUT / POST
write


Read (Retrieve)
SELECT
GET
read / take


Update (Modify)
UPDATE
PUT / PATCH
write


Delete (Destroy)
DELETE
DELETE
dispose

Operation	SQL	HTTP	DDS
Create	INSERT	PUT / POST	write
Read (Retrieve)	SELECT	GET	read / take
Update (Modify)	UPDATE	PUT / PATCH	write
Delete (Destroy)	DELETE	DELETE	dispose

There is also @HEAD, today we will stick to @GET only, and cover remaining CRUD operations next week.

Building a response:

Response object helps you build meaningful responses

package test;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
 
@Path("sandbox")
public class Sandbox {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("response")
    public Response getIt() {
        return Response.status(200).entity("this is what we actually return").build();
    }
}

http://localhost:8080/unh/rest/sandbox/response

You can use Postman REST client to see the header information that is being sent back

https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en

Response status constants can be user in place of explicit codes:

return Response.status(Response.Status.OK).entity("Good Response").build();




ACCEPTED
202 Accepted, .


BAD_REQUEST
400 Bad Request, .


CONFLICT
409 Conflict, .


CREATED
201 Created, .


FORBIDDEN
403 Forbidden, .


GONE
410 Gone, .


INTERNAL_SERVER_ERROR
500 Internal Server Error, .


MOVED_PERMANENTLY
301 Moved Permanently, .


NO_CONTENT
204 No Content, .


NOT_ACCEPTABLE
406 Not Acceptable, .


NOT_FOUND
404 Not Found, .


NOT_MODIFIED
304 Not Modified, .


OK
200 OK, .


PRECONDITION_FAILED
412 Precondition Failed, .


SEE_OTHER
303 Other, .


SERVICE_UNAVAILABLE
503 Service Unavailable, .


TEMPORARY_REDIRECT
307 Temporary Redirect, .


UNAUTHORIZED
401 Unauthorized, .


UNSUPPORTED_MEDIA_TYPE
415 Unsupported Media Type, .

TRY IT YOURSELF:

Write a REST service that takes 2 URL Path Parameters and adds them returning a third parameter. If the user passes a bad argument, return a Bad Request response.

ex.
http://localhost:8080/unh/rest/sandbox/add/4/5 should return HTTP OK 200 and entity 9
http://localhost:8080/unh/rest/sandbox/add/4/f should return HTTP 400 and some error message

Query Parameters:

You can also pass the query parameters to your application

http://localhost:8080/unh/rest/sandbox/add?var1=4&var2=7

package test;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
 
@Path("sandbox")
public class Sandbox {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("add")
    public Response getIt(@QueryParam("var1") String var1, @QueryParam("var2") String var2) {
    	try{
    		int result = Integer.parseInt(var1) + Integer.parseInt(var2);
    		return Response.status(Response.Status.OK).entity(result).build();
    	}
    	catch(Exception e){
    		return Response.status(Response.Status.BAD_REQUEST).entity("Please make sure you pass integers").build();
    	}
    }
}

You can also pass Lists (Arrays) of parameters:

package test;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
 
@Path("sandbox")
public class Sandbox {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("add")
    public Response getIt(@QueryParam("goods") List goods) {
    	try{
    		return Response.status(Response.Status.OK).entity(goods.toString()).build();
    	}
    	catch(Exception e){
    		return Response.status(Response.Status.BAD_REQUEST).entity("Please make sure you pass integers").build();
    	}
    }
}

Now hitting http://localhost:8080/unh/rest/sandbox/add?goods=cup&goods=table would return [cup, table]

DefaultValue

package test;

import java.util.List;

import javax.ws.rs.DefaultValue;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
 
@Path("sandbox")
public class Sandbox {
 
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("add")
    public Response getIt(@DefaultValue("something") @QueryParam("goods") List goods) {
    	try{
    		return Response.status(Response.Status.OK).entity(goods.toString()).build();
    	}
    	catch(Exception e){
    		return Response.status(Response.Status.BAD_REQUEST).entity("Please make sure you pass integers").build();
    	}
    }
}