API Response Trait

[lonnieezell]

This trait would provide a standardized way to respond from controllers when creating an API. The primary benefits are 2-fold:

1. More readable HTTP responses for a variety of common situations.
2. Best practices for the responses will be used so the developer doesn't have to think about which HTTP status to use in each situation.

[NEEDS MORE INFO]

Development Checklist:

• Component(s)
• ... with PHPdocs
• Unit testing
• ... with >80% coverage
• User guide updated
• Classmap integration?
• Securely signed commits
• Conforms to style guide

[prezire]

Are you referring to a simplified version of Laravel's Resource Controllers? https://laravel.com/docs/5.3/controllers#resource-controllers

[lonnieezell]

Nope. CI already has Resourceful Routes. In this, I'm talking about common response methods for a number of the most frequently used responses in API's. This would set the correct HTTP status code, default message, etc and send the response, thus helping a user keep a consistent, and accurate response when doing RESTful API's.

I've got one of these partially finished that I've used in a few other projects that I need to revisit, expand, and re-research to ensure they're still meeting best practices.

[prezire]

You mean something like this?

// Structure.
{
  success: bool,
  status_code: int,
  data: array,
  message: string
}
// Sample success.
{
  success: true,
  status_code: 200,
  data: [{id: 1, full_name: 'a'}, {id: 2, full_name: 'b'}],
  message: 'Students list.'
}
// Sample failed.
{
  success: false,
  status_code: 404,
  data: [],
  message: 'Record not found.'
}
// Some method.
public function Api::response(int $statusCode, array $data, string $message);

[lonnieezell]

No, what I had used previously were a series of methods that made it easier to remember, like failValidation(), failUnauthorized(), etc. That way you didn't have to remember which status codes were for each state.

There's enough discussion about certain status' that it would be wise to make those customizable.

Another wrinkle is that we need to determine exactly how we're going to handle response formatting, if we do it at all. And there has been discussion internally about the possibility of formatting responses as XML, JSON, JSONP, etc, from model results, but no firm decision made just yet.

[prezire]

I see. Wouldn't it be best to use constants or static variables for the codes? But in any case, I'm excited for the final decision.