General Response Structure

The following article will give you a general structure of the expected behave and response objects. All communication is provided as JSON format.

Collection Request

Return status 200 and the requested collection

In case of a collection request, the general response structure is the following.

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "data": [
    {
       ...
    },
    ...
  ],
  "links": {
    ...
  },
  "meta": {
    ...
  }
}

Collections and Pagination

Collections return a specific amount of entries per request. links and meta are providing information to walk through the pages. meta.per_page shows the amount of objects per page.

{
  ...
  "links": {
    "first": "{link}?page=1",
    "last": "{link}?page=3",
    "prev": null,
    "next": "{link}?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "{link}?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "{link}?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "{link}?page=3",
        "label": "3",
        "active": false
      },
      {
        "url": "{link}?page=2",
        "label": "Next »",
        "active": false
      }
    ],
    "path": "{link}",
    "per_page": 50,
    "to": 2,
    "total": 6
  }
}

Request Single Object

Returns status 200 and the requested object

If a specific object is requested, the data field always contains id, and created_at.

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "data": {
    "id": 1,
    ...
    "created_at": "2021-09-03T12:40:43+00:00"
  }
}

Related objects most of the time have a minimum set of fields. They can be reviled by calling the related endpoint with the ID in the URL.

{
  "data": {
    "id": 1,
    ...
    "related_object": {
       "id": 45,
       ...
    }
  }
} 

Validation Errors

Return status 422 message and error object

In case of a validation error, the response will contain message and errors for more details.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
...

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email has already been taken.",
      "..."
    ],
    ...
  }
}

Successful Update Response

Returns status 200 and updated object

A successful update response returns the updated object in total with an HTTP status of 200.

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "data": {
    "id": 1,
    ...
  }
}

Object not Found

Returns status 404 and message

If a requested object could not be found, the HTTP status is 404.

HTTP/1.1 404 Not Found
Content-Type: application/json
...

{
  "message": "Object not found"
}

Bad Request

Returns status 400 and message

Most of the time, POST PATCH PUT request can't have an empty request object. This message may hint at an error in the JSON syntax.

HTTP/1.1 400 Bad Request
Content-Type: application/json
...

{
  "message": "Empty request, check your JSON syntax."
}