How to Identify REST Resources


This is the first step in design RESTful Web service. In this post, we will learn how to identify resources from use cases and a description of the web service.

To understand better divide the topic into multiple sections like problem statement, solution, case study, and examples. First, the resource published on the Web is extracted. Both object-oriented design and database modeling techniques use domain entities as a basis for design. You can use the same technique to identify resources. But be warned.

Problem Statement

You want to start identifying resources from the use cases and a description of the web service.

Solution

Analyze your use cases to find domain nouns that can be operated using “create,” “read,” “update,” or “delete” operations. Designate each noun as a resource. Use POST, GET, PUT, and DELETE methods to implement “create,” “read,” “update,” and “delete” operations, respectively, on each resource.

Precautions should be taken while extracting a resource

I suggest few precautions should be taken while extracting a resource are:
  • Resource published on the web is used as the information managed by the database. However, the data model of the database must not be published as a resource as it is, without careful consideration. It should be closely investigated, as the fields stored in the database may include some fields that should not be disclosed to the client.
  • When information type is different in spite of being managed by the same table of the database, publishing it as a separate resource may be considered. There are cases wherein, even if essentially seen as different information, it is managed by the same table, due to a same data structure. Hence, such cases need to be reviewed closely.
  • In RESTful Web Service, the information operated by an event is extracted as a resource. The event itself should not be extracted as a resource. For example, when creating RESTful Web Service to be called from the events (approve, deny, return etc.) generated by workflow functionality, information for managing the workflow status or the workflow itself, is extracted as a resource.

Case Study 1

Consider a web service for managing photos. Clients can upload a new photo, replace an existing photo, view a photo, or delete a photo. 

In this example, “photo” is an entity in the application domain. The actions a client can perform on this entity include “create a new photo,” “replace an existing photo,” “view a photo,” and “delete a photo.” You can apply this recipe to identify each “photo” as a resource such that clients can use HTTP’s uniform interface to operate on these photos as follows:
  • Method GET to get a representation of each photo 
  • Method PUT to update a photo 
  • Method DELETE to delete a photo 
  • Method POST to create a new photo 
This recipe is what gives REST the perception that REST is suitable for CRUD-style (Create, Read, Update, Delete) applications only.

Case Study 2

Let's consider the User Management System where we need CRUD Rest API for User Entity. How to identify the resource in this example and apply all best practices to assign URL to the resource.
I Suggest below are the standard RESTful API for User Management System.
  • HTTP Method GET  Path : /api/v1/users
  • HTTP Method GET  Path : /api/v1/users/100
  • HTTP Method POST Path : /api/v1/users
  • HTTP Method DELETE Path : /api/v1/users/101
  • HTTP Method PUT  Path : /api/v1/users/102
  • HTTP Method POST Path : /api/v1/users/active
  • HTTP Method POST Path : /api/v1/users/deactive

Comments