The Jres specification establishes how to format JSON RESTful API responses.
The specification assumes that there is always either a data
key, or an error
key. Both can not be present. If the response contains the data
key, the API request has succeeded. If the error
key is present, the API request did not succeed. All responses are enveloped.
Key | Is Required | Description |
---|---|---|
data |
✔ | Holds the API payload |
A successful response is only required to have a data
key. This will hold the API response's payload. If there is no payload, like in the case of a record deletion, data
would be set to null
.
{
"data": [
{
"id": 1,
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]"
},
{
"id": 2,
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
},
{...},
{...}
]
}
{
"data": {
"id": 1,
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]"
}
}
data
can benull
if the response does not have a payload, like a DELETE endpoint.
{
"data": null
}
Key | Is Required | Description |
---|---|---|
error |
✔ | The error object key is used to determine if the response was successful or not. |
error.message |
✔ | The error.message key is a UI friendly message that can be used on the client side to describe the error. |
error.code |
A code that can be used to describe a specific error within your application. This is different than a status code. | |
error.validationErrors |
If your error is due to incorrect input, use error.validationErrors . This key stores an object such that the keys are the HTML id of the invalid field, and the value is the error message to be displayed on the client side. |
An unsuccessful response will always include an error
key. That way, you can check if your response succeeds or not by simply checking if the error
key is in the response. Here is an example in JavaScript:
fetch(`/users/`, {
method: 'GET'
})
.then(res => res.json())
.then(res => {
// Check for error in response.
if(res.error) {
throw error
}
// API Request succeeded, use data.
console.log(data)
})
.catch(err => console.log(err))
{
"error": {
"message": "There was an issue connecting to the database.",
"code": "DATABASE_CONNECTION_FAILED"
}
}
{
"error": {
"message": "Some of the inputs you entered are incorrect.",
"code": "CREATE_USER_VALIDATION_FAILED",
"validationErrors": {
"email": "This email has already been used",
"password": "The password must be at least 8 characters"
}
}
}
The Jres specification was created by Blake Wilson. The specification and this website are open source, and are released under the MIT license.