What Http method have I to use to modify this REST resource and what response code have I to return?

Question

I am pretty new in RESTful web services and I have the following doubt. I am working on a Spring MVC application (but this is not so important because my doubt is more related to REST concept).

I have this domain class:

@Entity
@Table(name = "accomodation_media")
public class AccomodationMedia {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Long id;

    //@Column(name = "accomodation_fk")
    //private Long idAccomodation;

    @ManyToOne
    @JoinColumn(name = "accomodation_fk", nullable = false)
    private Accomodation accomodation;

    @Column(name = "is_master")
    private boolean isMaster;

    @Lob
    @Column(name = "media")
    private byte[] media;

    private String description;

    private Date time_stamp;

    .................................................................
    .................................................................
    GETTER AND SETTER METHODS
    .................................................................
    .................................................................
}

That represent records into the room_media table of my database.

Then I have a controller method that handle HTTP Requesto toward the URL: /Accomodation/{accomodationId}/accomodationMedia/{mediaId}.

Something like this:

@RequestMapping(value = "/{accomodationId}/accomodationMedia/{newMasterImgId}", method = RequestMethod.XXXX)
public ResponseEntity<String> changeMasterImg(@PathVariable Long accomodationId,
                                              @PathVariable Long newMasterImgId) throws Exception {

    accomodationMediaService.changeMasterImg(accomodationId, newMasterImgId);

    return ResponseEntity.ok("Master Image cambiata");

}

This method call the changeMasterImg() that basically retrieve an AccomodationMedia instance from the database, change the value of the isMaster field and update it.

So basically this method handle a partial update because it now insert a brand new object but retrieve an object, modify it and update it.

So my doubts are:

1) According to RESTful standard have I to use POST as request to update the AccomodationMedia resource? I have read that maybe I can also use PATCH for a partial update. What is the difference between the use of POST and PATCH Http Method? What is the best in this case?

2) What kind of status code response have I to return in case of successful update? Here: Best practice for partial updates in a RESTful service

It say 303 but way 303 that should be a redirectional message and not something like 200 that means that the operation is ok?

As I consumer of REST service I would like to deal with simpest API as much as possible, whitout weird redirect codes(303 see others codes) or PATCH Http methods. I don't really beleive that any serious public API follows REST best practice — Anton, Jan 06 '17 at 15:28
@Anton and so what you think that could be the best choice in this case? — AndreaNobili, Jan 06 '17 at 15:31

score 2 · Accepted Answer · answered Jan 06 '17 at 15:34

As a general rule, CRUD operations should follow this pattern:

POST: Create
PUT: Update
GET: Read
DELETE: Delete

If the operation was successful, I would return a 2xx code. 3xx codes are for redirection which you're not doing here.

If you're returning success and a payload of data: 200 If you're returning success and no content, then: 204

A good resource for working with REST responses: http://www.restapitutorial.com/httpstatuscodes.html

score 1 · Answer 2 · edited Oct 07 '21 at 11:39

You have also to take the PUT HTTP method into consideration. According to restcookbook.com :

Use PUT when you can update a resource completely through a specific resource. For instance, if you know that an article resides at http://example.org/article/1234, you can PUT a new resource representation of this article directly through a PUT on this URL.

If you do not know the actual resource location, for instance, when you add a new article, but do not have any idea where to store it, you can POST it to an URL, and let the server decide the actual URL.

About PATCH :

The HTTP methods PATCH can be used to update partial resources.

For the response status code, I would prefer 200 OK, or 201 Created

In addition of the restcookbook, I also recommend the RFC 7231 which is the authoritative reference.

What Http method have I to use to modify this REST resource and what response code have I to return?

2 Answers2