Designing Resful services

In my previous post, i had given basic overview of REST. In this post, i am going to explain the APIs that we are going to develop throughout the tutorial.

In this tutorial series we are going to develop apis for a company ‘X’ to maintain employee information.

Following are the requirements

a.   We should get all the employees details

b.   We should get employee details by id

c.    We can add new employee

d.   We can remove existing employee

e.   We can get employees staying in particular city

f.     We can get employees from given id to size. If id =5, size = 10, we should get employees with ids 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15.

g.   We should get employee permanent address.

h.   We should get employee temporary address.

i.      Update specific employee

Now we had requirements, we need to decide which HTTP methods (GET, POST, PUT, DELETE), we should assign to each requirement.

Read-Only requests

Requirements a, b, e, f, g, h ae read-only requests, so we can assign GET method to these requirements.

Creating new resource

Requirement ‘c’ delas with creating new employee. So it should be a POST request.

Updating existing resource

Requirement 'i', updates existing employee details, so it is a PUT request.

Delete existing resource

Requirement 'd' is a DELETE request.

Following are the URIs that we are going to develop.

URI	Method	Description
/employees	GET	Return all employees
/employees	POST	Add new employee
/employees/{employeeID}	GET	Get employee details for given id
/employees/{employeeID}	PUT	Update specific employee
/employees/{employeeID}	DELETE	Delete employee details for given id
/employees?city=Bangalore	GET	Get all employees staying at Bangalore
/employees?start=1&size=2	GET	Get all employees with ids 1, 2 and 3
/employees/{employeeID}/address/permanentAddress	GET	“/employees/1/address/permanentAddress” gets Permanent address of employee 1.
/employees/{employeeID}/address/temporaryAddress	GET	“/employees/1/address/temporaryAddress“ gets Temporary address of employee 1.

We are going to develop above APIS one by one.

Post 3 shows you how to setup Jersey environment to run Hello World application.

Post 4 builds /employees api (GET), which returns xml response of all employees.

Post 5 builds /employees/{employeeId} (GET), which returns xml reponse of employee for given id

Post 6 shows how to return json response as output

Post 7 builds /employees api (POST) to add new employee

Post 8 builds /employees/{employeeId} (PUT, DELETE) to update, delete existing employee

Post 9 builds apis /employees?city=Bangalore, /employees?start=5&size=6 (these use query parameters)

Post 10 builds apis /employees/{employeeId}/address/temporaryAddress, /employees/{employeeId}/address/permanentAddress

post 11 explains how to set response codes and headers

Post 12 explains how to handle exceptions using Jersey framework

Post 13 explains about HATEOAS

Post 14 explains about content negotiation, where our apis send response based on client intrest. If client want json response, api send json response, if client want xml response, api send xml response.

Post 15 explains Jersey REST client API.

Post 16 explains complete Rest client fot the application we developed in post 14.

Prevoius                                                 Next                                                 Home