3

I am developing a RESTful API and I am using DAOs to serve data to the service.

I am having trouble deciding where certain responsibilities should fall, whether in the service or in the DAO contract. Or not just responsibilities but just deciding what each component should do or should not do.

In the scenario of the CRUD part of the API, let's focus in the create functionality, for example. When a resource is created (or not), what response is expected from the service? The serialized object that has been created? A true/false message? Nothing? This is what I mean:

// Option 1
@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Resource createResource(Resource resource) {
    dao.create(resource);
    return resource;
}

// Option 2
@POST
@Consumes(MediaType.APPLICATION_JSON)
public void createResource(Resource resource) {
    dao.create(resource);
}

// Option 3
@POST
@Consumes(MediaType.APPLICATION_JSON)
public String createResource(Resource resource) {
    return dao.create(resource); // or even a custom message?
}

But going further. What should the DAO return? Should the dao.create() method return a boolean? Should it return the created object, or null if it couldn't be created? Or just be void?

// Option 1
public Resource create(Resource resource) {
    return resources.add(resource) ? resource : null;
}

// Option 2
public void create(Resource resource) {
    resources.add(resource);
}

// Option 3
public boolean create(Resource resource) {
    return resources.add(resource);
}

I just want to figure out what is usually expected from a RESTful service and then, decide what is the best division of "who should do what".

Or I am just overthinking this and any implementation makes sense and is as good as the other?

  • I would like use this question to ask if it's not quite risky to expose DAO in this way. Is it common on API web developments? May be I tend too much to use layers and TO (for responses), what brings complexity to my developments. – Laiv Jun 3 '16 at 17:16
  • @Laiv It is, unfortunately, very common to use a web API to simply directly expose your data model. Sometimes that's the right thing to do, but often it isn't. In this case, there's nowhere near enough information for anybody reading the question to say one way or the other. I would not feel bad at all about your API resources not directly mapping back to database tables. – Eric Stein Jun 3 '16 at 18:03
  • @EricStein Thank you for your answer. I think I will keep decoupling resources like I use to do. I cant easly explain why I feel myself more confident doing it on this way. Thx again. – Laiv Jun 3 '16 at 18:40
3

It's common for DAOs to return the newly-created resource, particularly when an ORM is used behind the scenes, for a couple of reasons I can think of:

  1. The returned object often has its surrogate primary key set, but more importantly -

  2. The returned object is often attached to the database session so further changes might automatically be committed when the session is closed.

In your example this isn't terribly important, but it's convenient when the more complex business logic is involved. None of the options you include follow this pattern.

As for REST endpoints, I agree with Eric, but I would add that on successful creation, respond with status code 201, the Location header set to the canonical URL of the new resource, and the serialized resource itself in the response body. Your Option 1 comes closest to this.

  • +1 for Location header and specifying the correct status code. – Eric Stein Jun 3 '16 at 16:02
3

For performance reasons, it's nice if an HTTP API call that creates a resource returns a representation of that resource to the client. Otherwise they have to do a separate GET call to get the resource.

The success or failure of the request should be conveyed by the status code in the response - 2xx codes for success, 4xx and 5xx codes for errors. You shouldn't ever need* to send a message or boolean indicating success or failure, but in the case of a failure you should send a message indicating what went wrong.

[*] Some people like to anyway, because it can be convenient for some clients to have that information in the response. That's in addition to the status code, not instead of.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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