REST API DESIGN - Get/Post/Put a resource through REST with different parameters

Question

I have a question related to RESTful api design. I have a RESTful api to GET/POST/PUT resource(user). I am not quite clear if my design is correct

Here is an example

/users:
  get:    
    queryParameters: 
      joinDate:
        displayName: get all used based on join date          
  post:
    displayName: Add new user

/{lastName}:
    get:
      displayName: Get all users based on last name   
/{id}:
    put:
      displayName: Update a particular user

I just wanted to know if the above design is good..

All help appreciated !

Answer 1

CRUD (Create, Read, Update, Delete) means the basic operations to be done in a data repository. You directly handle records or data objects; apart from these operations, the records are passive entities. Typically it's just database tables and records.

REST, on the other hand, operates on resource representations, each one identified by an URL. These are typically not data objects, but complex objects abstractions.

For example, a resource can be a user's comment. That means not only a record in a 'comment' table, but also its relationships with the 'user' resource, the post that comments, maybe another comment that it answers.

Operating on the comment isn't a primitive database operation, it can have significant side effects, like firing an alert to the original poster, or recalculating some gamelike 'points', or updating some 'followers stream'.

Also, a resource representation includes hypertext (check the HATEOAS principle), allowing the designer to express relationships between resources, or guiding the REST client in an operation's workflow.

In short, CRUD is a set primitive operations (mostly for databases and static data storages), while REST is a very-high-level API style (mostly for webservices and other 'live' systems).

The first one manipulates data, the other interacts with a working system.

to Learn more about CRUD

so from my perspective you are completely Correct!

Answer 2

I would do like this.

POST /users
    Creates a single user

GET /users
    Reads all users

GET /users;joinDate=yyyy-MM-dd
    Reads all users whose join date matches to given

GET /users;joinDate=yyyy-MM-dd;lastName=Some
    Reads all users whose join date matches to given 
    and whose last name matches to given

GET /users/{userId}
    Reads a user whose {id} matches to given

GET /users;joinDate=yyyy-MM-dd/{userId}
    Reads a user whose id matches to given
    among those who joined on specified day.