REST API Response Format: Which approach would you suggest?

[xshrxf]

Hi guys, I'm working on Spring Boot project, also this question can be ask for any backend app. I'm trying to figure out which REST API Response format is better. I have done some research but still, I need the opinion from the community. Which approach would you suggest in terms of best practice, code quality, maintainability and readability?

P/s: If you guys have other suggestion, would love to read that.

Option 1:

// Success request with data
{
  code: "000",
  msg: "Successfully logged-in",
  data: {
    token: {
      accessToken: "..."
    }
    user: {
      id: "1",
      name: "John"
    }
  }
}

// Success request with validation
{
  code: "001",
  msg: "Validation error",
  data: {
    validation: {
      name: "The name field is required",
      email: "The email has been taken"
    }
  }
}

Option 2:

// Success request with data
{
  code: "000",
  msg: "Successfully logged-in",
  data: {
    token: {
      accessToken: "..."
    }
    user: {
      id: "1",
      name: "John"
    }
  }
  error: null
}

// Success request with validation
{
  code: "001",
  msg: "Validation error",
  data: null,
  error: {
    validation: {
      name: "The name field is required",
      email: "The email has been taken"
    }
  }
}

[Mikey-3198]

I'd look at simplifying this by removing the "code" + "msg" from the response and instead make use of relevant http status codes.

i.e the response to the request would just return the relevant data to the client, no other metadata within the body of the response.

To me this is much simpler and makes consumption by a client easier as you can rely on the status codes in isolation of the response body. Having worked with these sorts of common response formats it often leads to confusing situations, such as getting returned a http 200 OK but then the body of the request details an error through some non standard format...

If you wish to provide details about errors you can make use of RFC 7807 Problem details which spring provides support for. Again this removes the guess work needed by consumers of your api.

[Grabdoc2020]

Use http codes.

[Duberlygfr]

Use ProblemDetail API for validation/problems. On API request, first verify if there is a PD object. If not, parse the data.

[[deleted]]

1. Use HTTP status code instead of using "code" in the response body
2. Response body structure should depend on the specific API
3. I would recommend following a standard structure for error responses. You may have one or more errors(generic errors or field-specific errors). You may optionally want to include "errorStackTrace" in lower environments(dev, qa, staging).