13

I'm working on a RESTful API and I'm having some trouble wrapping my head around the procedure for supplying input to the API.

Let's say I have a "Person" resource that can be fetched like this: api/person/{id} and returns an object like this:

public class Person
{
    public int Id { get; set; }
    public string Surname { get; set; }
    public string GivenName { get; set; }
    public DateTime DateOfBirth { get; set; }
}

If I want to update that person, should the API be expecting a full Person instance, or is it acceptable to use a separate DTO?

Let's say for example the DateOfBirth cannot be changed, is it considered RESTful to accept this as input:

public class UpdatePersonDto
{
    public string Surname { get; set; }
    public string GivenName { get; set; }
}

This would mean I would have this endpoint api/person/{id} returning Person when using GET, while accepting as input UpdatePersonDto when using PUT. This sounds wrong to me, but I'm not sure if I'm just being paranoid.

So I guess my question sums up to this: Is it suitable to accept a data structure on a given resource endpoint that differs from what that endpoint would return?

2
  • 1
    Downvoters - care to comment?
    – Nick Coad
    Aug 4, 2015 at 6:30
  • Unfortunately, very rarely. Upvoted.
    – Opal
    Aug 4, 2015 at 7:57

2 Answers 2

2

When it comes to REST strict rules (as far as such rules even exists :/) you should send the whole entity to PUT. Now you can:

  1. Silently ignore the fields that cannot be updated - recommended in some cases but should be documented.
  2. Throw an exception if you detect that a field that cannot be updated was given a new value.
  3. Instead of using PUT, use PATCH which can update a group of fields, and the whole entity is not necessary, e.g. only first and last name can be sent.

Personally I think that the best option is 1 or 3. What I'd not suggest is introducing new endpoints as suggested by @morsor. Such endpoints always introduce a mess. Generally, the less endpoints are used to better (cleaner, easier to understand) the API is.

1

It seems the REST consensus is that when updating using PUT, one supplies the entire entity to replace.

Programmatically, it would work having PUT /person/{id} accepting input which behind the scenes maps to UpdatePersonDTO instead of Person.

The only 'problem' could be that it does go against the general expectation.

A middle-ground solution could be POST (or PUT) /person/{id}/mutables which could accept the UpdatePersonDTO.

Edit: Or parhaps more obviously: PUT /person/{id}/name which takes a PersonName argument containing the two fields.

4
  • That makes a lot of sense for PUT, where you can fetch a copy of the resource, modify it, and send it back. But what about POST, where some properties may be calculated server-side during the creation process?
    – Nick Coad
    Aug 4, 2015 at 6:06
  • 2
    I'm not sure what you feel the problem is. PUT should be idempotent (to the client), while using POST clearly states that non-idempotent actions on the server should be expected.
    – morsor
    Aug 4, 2015 at 6:10
  • In this case I'm not talking about whether the request gets handled in an idempotent way on the server, I'm talking about whether it is considered correct practice to POST a DTO with only those fields necessary for creating a resource, or should I be POSTing an actual instance of the resource with as many fields populated as possible?
    – Nick Coad
    Aug 4, 2015 at 6:30
  • Since REST is not a standard, there are a lot a gray areas which leave a lot of wiggle room. IF you are able to populate the entire object client-side, performing a standard PUT with the entire object would conform 100% with REST best practice. Your other solutions are perfectly legal, the only issue being that you will need to document them better, as you are not following the expected best practice.
    – morsor
    Aug 4, 2015 at 6:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.