Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/blakewilson/jres
The Jres specification establishes how to format JSON RESTful API responses.
https://github.com/blakewilson/jres
api http1-1 json rest
Last synced: 8 days ago
JSON representation
The Jres specification establishes how to format JSON RESTful API responses.
- Host: GitHub
- URL: https://github.com/blakewilson/jres
- Owner: blakewilson
- License: mit
- Created: 2019-11-24T19:57:36.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T07:46:02.000Z (almost 2 years ago)
- Last Synced: 2024-11-01T16:51:28.989Z (about 2 months ago)
- Topics: api, http1-1, json, rest
- Language: JavaScript
- Homepage: https://jres.dev
- Size: 899 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[
](https://jres.dev)
# The Jres Specification
## Introduction
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.
## Examples
### Successful Responses
| 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`.
#### GET /users
```json
{
"data": [
{
"id": 1,
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]"
},
{
"id": 2,
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
},
{...},
{...}
]
}
```
#### GET /users/:userId
```json
{
"data": {
"id": 1,
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]"
}
}
```
#### DELETE /users/:userId
> `data` can be `null` if the response does not have a payload, like a DELETE endpoint.
```json
{
"data": null
}
```
### Unsuccessful Responses
| 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](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). |
| `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](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/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:
```js
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))
```
#### GET /users
```json
{
"error": {
"message": "There was an issue connecting to the database.",
"code": "DATABASE_CONNECTION_FAILED"
}
}
```
#### POST /users
```json
{
"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](https://github.com/blakewilson). The specification and this website are [open source](https://github.com/blakewilson/jres), and are released under the [MIT license](https://github.com/blakewilson/jres/blob/master/LICENSE).