Developing Quality API with Laravel - Tip #4
Tags: laravel, api, discuss
Published: 2023-06-03 19:20:38

###Tip #4 - Create a consistent response structure.

What do I mean by this? 

I've been developing APIs for the better part of my career, and there is nothing more annoying than an API with an inconsistent structure. 

Sometimes it returns a `status_code`, sometimes it doesn't! Believe me, I've seen it; and they were not dummy APIs, they were very well known and publicly used, but since there was no other alternatives, people couldn't switch to a better one. 

So I thought to myself, if I want to see some changes, why not start it myself? 

I started thinking, there SHOULD be a rule, or a convention to suggest a structure for web APIs. I searched for it and found [RFC-7808](https://www.rfc-editor.org/rfc/rfc7807).

But wait, RFC-7807 is only for error reporting side of an API, what about the time when there are no errors? What about that structure? 

I couldn't find a good answer to this question, and frankly I got tired of searching the web for something that apparently doesn't exist. 

So I wore my engineering hat and started thinking. 

I wanted to come up with a structure for APIs that could handle both error and non-error responses and after a bit of thinking, I came up with this:

```json
{
  "status": null,
  "title": null,
  "detail": null,
  "data": [],
  "errors": []
}
``` 
Let me explain: 

`status`: The HTTP status code sent from the server, ranging from 1xx to 5xx.
`title`: A general, human-friendly message to show to the client.
`detail`: A specific, human-friendly message explaining the situation in finer detail.
`data`: The data that is fetched from the server to be displayed to the client.
`errors`: An array of errors with a specific message explaining the error.

Think about it; not only it supports errors, but also, it supports non-error responses. Right? So the structure would never change inside the API. That's cool.

Let's see some examples:

Let's say you want to see a list of all the products in your web shop: 

```json
{
  "status": 200,
  "title": "Data successfully fetched.",
  "detail": null,
  "data": [
    {
      "id": 1,
      "name": "Some Imaginary Product",
      "price": 10,
      "currency": "USD"
    },
    {
      "id": 2,
      "name": "Another Imaginary Product",
      "price": 15,
      "currency": "USD"
    }
  ],
  "errors": []
}
```
Or maybe when you want to create a new product for the web shop:

```json
{
  "status": 201,
  "title": "Record successfully created!",
  "detail": "A new product was added to the web shop.",
  "data": [
    {
      "id": 1,
      "name": "Some Imaginary Product",
      "price": 10,
      "currency": "USD"
    }
  ],
  "errors": []
}
```
What about when you fail to send valid data to create a product? 

```json
{
  "status": 400,
  "title": "Request failed!",
  "detail": "Request parameters did not pass validation tests; please fix them and retry again.",
  "data": [],
  "errors": {
    "name" : "Field `{name}` is required.",
    "price" : "Field `{price}` needs to be an integer."
  }
}
```

What do you think? Is this a reliable structure? Could you think of any problems with it? 

I may publish this idea as a third party package on GitHub (if it's any good); I've applied to one of my projects and so far it holds up pretty good.

I'm looking forward to hearing from you and improving this idea.

---

[Link to cover image](https://unsplash.com/photos/gi1f13S1-64)