What should resources in a REST service be like?

Question

I am developing an application based on REST services. I've read everything about developing REST web service but one thing confusing me. As I read, all the module or functionality must have unique and meaningful resource name like

http://localhost:8080/rest/create-organization

and

http://localhost:8080/rest/add-employee

But one of my colleagues suggested me that we should have only one resource as a single landing point for all modules and we must send some code in request header to recognize which functionality we want to execute. For example:

http://localhost:8080/rest/application

And, in request header, we should add CRTORG parameter for creating organization and ADDEMP for adding an employee.

On the basis of this keywords we will call appropriate method and will return response.

Is it the right way? If no why?

Answer 1

That's not how REST applications are supposed to be. See more details below.

REST resources

REST stands for Representational State Transfer and this architecture was defined by Roy Thomas Fielding in the chapter 5 of his dissertation .

The key concept of this architecture is the resource . See the following quote from the Fielding's dissertation:

5.2.1.1 Resources and Resource Identifiers

The key abstraction of information in REST is a resource. Any information that can be named can be a resource : a document or image, a temporal service (eg "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (eg a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time. [...]

REST is protocol independent and, when implemented over the HTTP protocol, the resources can be manipulated with HTTP verbs and the resources are identified by theirs URIs. The same resource can have different representations, such as JSON and XML.

For more details regarding resources and resource representations, see this answer .

What your API could be like

Your API could have the following endpoints and operations:

• Create an organization (sending the resource representation in the request payload)

   POST /api/organizations 

• Get all organizations

   GET /api/organizations 

• Get an organization using a certain identifier

   GET /api/organizations/{organizationId} 

• Replace an organization using a certain identifier (sending the resource representation in the request payload)

   PUT /api/organizations/{organizationId} 

• Delete an organization using a certain identifier

   DELETE /api/organizations/{organizationId} 

• Create an employee for an organization (sending the resource representation in the request payload)

   POST /api/organizations/{organizationId}/employees 

• Get all employees for an organization

   GET /api/organizations/{organizationId}/employees 

• Get an employee for an organization

   GET /api/organizations/{organizationId}/employees/{employeeId} 

• Replace an employee of an organization (sending the resource representation in the request payload)

   PUT /api/organizations/{organizationId}/employees/{employeeId} 

• Delete an employee from an organization

   DELETE /api/organizations/{organizationId}/employees/{employeeId}