• Stars
    star
    1,468
  • Rank 32,033 (Top 0.7 %)
  • Language
  • License
    BSD 3-Clause "New...
  • Created almost 6 years ago
  • Updated almost 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

JSend is a specification for a simple, no-frills, JSON based format for application-level communication.

JSend

  • What? - Put simply, JSend is a specification that lays down some rules for how JSON responses from web servers should be formatted. JSend focuses on application-level (as opposed to protocol- or transport-level) messaging which makes it ideal for use in REST-style applications and APIs.
  • Why? - There are lots of web services out there providing JSON data, and each has its own way of formatting responses. Also, developers writing for JavaScript? front-ends continually re-invent the wheel on communicating data from their servers. While there are many common patterns for structuring this data, there is no consistency in things like naming or types of responses. Also, this helps promote happiness and unity between backend developers and frontend designers, as everyone can come to expect a common approach to interacting with one another.
  • Hold on now, aren't there already specs for this kind of thing? - Well... no. While there are a few handy specifications for dealing with JSON data, most notably Douglas Crockford's JSONRequest proposal, there's nothing to address the problems of general application-level messaging. More on this later.
  • (Why) Should I care? - If you're a library or framework developer, this gives you a consistent format which your users are more likely to already be familiar with, which means they'll already know how to consume and interact with your code. If you're a web app developer, you won't have to think about how to structure the JSON data in your application, and you'll have existing reference implementations to get you up and running quickly.

So how does it work?

A basic JSend-compliant response is as simple as this:

{
    status : "success",
    data : {
        "post" : { "id" : 1, "title" : "A blog post", "body" : "Some useful content" }
     }
}

When setting up a JSON API, you'll have all kinds of different types of calls and responses. JSend separates responses into some basic types, and defines required and optional keys for each type:

TypeDescriptionRequired KeysOptional Keys
successAll went well, and (usually) some data was returned.status, data
failThere was a problem with the data submitted, or some pre-condition of the API call wasn't satisfiedstatus, data
errorAn error occurred in processing the request, i.e. an exception was thrownstatus, messagecode, data

Example response types

Success

When an API call is successful, the JSend object is used as a simple envelope for the results, using the data key, as in the following:

GET /posts.json:

{
    status : "success",
    data : {
        "posts" : [
            { "id" : 1, "title" : "A blog post", "body" : "Some useful content" },
            { "id" : 2, "title" : "Another blog post", "body" : "More content" },
        ]
     }
}

GET /posts/2.json:

{
    status : "success",
    data : { "post" : { "id" : 2, "title" : "Another blog post", "body" : "More content" }}
}

DELETE /posts/2.json:

{
    status : "success",
    data : null
}

Required keys:

  • status: Should always be set to "success".
  • data: Acts as the wrapper for any data returned by the API call. If the call returns no data (as in the last example), data should be set to null.

Fail

When an API call is rejected due to invalid data or call conditions, the JSend object's data key contains an object explaining what went wrong, typically a hash of validation errors. For example:

POST /posts.json (with data body: "Trying to creating a blog post"):

{
    "status" : "fail",
    "data" : { "title" : "A title is required" }
}

Required keys:

  • status: Should always be set to "fail".
  • data: Again, provides the wrapper for the details of why the request failed. If the reasons for failure correspond to POST values, the response object's keys SHOULD correspond to those POST values.

Error

When an API call fails due to an error on the server. For example:

GET /posts.json:

{
    "status" : "error",
    "message" : "Unable to communicate with database"
}

Required keys:

  • status: Should always be set to "error".
  • message: A meaningful, end-user-readable (or at the least log-worthy) message, explaining what went wrong.

Optional keys:

  • code: A numeric code corresponding to the error, if applicable
  • data: A generic container for any other information about the error, i.e. the conditions that caused the error, stack traces, etc.

Whither HTTP?

But wait, you ask, doesn't HTTP already provide a way to communicate response statuses? Why yes, astute reader, it does. So how does the notion of indicating response status in the message body fit within the context of HTTP? Two things:

  • The official HTTP spec has 41+ status codes, and there are many interpretations on how to use each one. JSend, on the other hand, defines a more constrained set of status codes, specifically related to handling JSON traffic in the context of a dynamic web UI.
  • The spec is meant to be as small, constrained, and generally-applicable as possible. As such, it has to be somewhat self-contained. A common pattern for implementing JSON services is to load a JavaScript file which passes a JSON block into a user-specified callback. JSON-over-XHR handling in many JavaScript frameworks follows similar patterns. As such, the end-user (developer) never has a chance to access the HTTP response itself.

So where does that leave us? Accounting for deficiencies in the status quo does not negate the usefulness of HTTP compliance. Therefore it is advised that server-side developers use both: provide a JSend response body, and whatever HTTP header(s) are most appropriate to the corresponding body.

License

The JSend specification (this page) is covered under a modified BSD License

More Repositories

1

pg_amqp

AMQP Support for Postgres
C
203
star
2

omnipitr

Advanced WAL File Management Tools for PostgreSQL
Perl
177
star
3

pg_jobmon

PostgreSQL extension which provides persistent logging within transactions and functions.
PLpgSQL
168
star
4

pg_extractor

PG Extractor - Advanced PostgreSQL Dump Filter
Python
161
star
5

pgtreats

Tasty treats for PostgreSQL
Perl
111
star
6

ansible-dk

An omnibus-based toolkit for working on Ansible-based infrastructure code.
Ruby
85
star
7

mimeo

Extension for specialized, per-table replication between PostgreSQL instances
PLpgSQL
78
star
8

jlog

JLog - Journaled Log
C
53
star
9

zetaback

Zetaback is a thin-agent based ZFS backup tool. It is designed to help simplify the task of backing up thousands of filesystems on hundreds of machines across and organization. It simplifies the task of automatically picking up newly created ZFS filesystems for backup purposes and restoring any given backup (host/FS/timestamp) to a target ZFS capable host.
Perl
39
star
10

omnios-build

Build system for OmniOS - Note, this is a quasi-private archive for OmniTI, you probably want https://omniosce.org
Shell
39
star
11

curo

postgres command-line tools
Shell
38
star
12

portableumem

This is a port of the Solaris umem memory allocator to other popular operating systems, such as Linux, Windows and BSDish systems (including Darwin/OSX).
C
30
star
13

Net--RabbitMQ

Perl bindings to the librabbitmq-c AMQP library.
C
25
star
14

resmon

Resmon is a lightweight utility for local host monitoring that can be queried by tools such as nagios over http. One of the main design goals is portability: that resmon should require nothing more than a default install of Perl. Built with the philosophy that "we are smart because we are dumb," that is, local requirements should be minimal to ease deployment on multiple platforms.
Perl
25
star
15

pg_query_statsd

Send query statistics to statsd
C
19
star
16

chef-solo-helper

Helper scripts for running chef-solo with a git backed repository
Shell
16
star
17

system_monitoring

Script for system monitoring
Perl
13
star
18

circus2

Various helper tools making use of the circonus v2 api
Python
6
star
19

db-failover

Postgres Failover Script
Perl
6
star
20

kayak

Kayak (PXE-enabled network imaging of OmniOS) - Note, this is a quasi-private archive for OmniTI, you probably want https://omniosce.org
Shell
6
star
21

circus

Python API client app and library for Circonus v1 API
Python
5
star
22

pgbrew

Pg Brew
Shell
4
star
23

pgOtter

PostgreSQL query log analyzer
Perl
4
star
24

svr42pkgsrc

SVR4 to pkgsrc conversion tools.
Shell
4
star
25

omnifab

Library of useful helper functions for fabric
Python
3
star
26

template-maker

Script to help automate the creation of configuration management templates from raw configuration files
Python
2
star
27

spreadlogd

Spreadlogd is a simple tool to log messages received via the Spread Group Communication system. It is primary used in conjuction with mod_log_spread to journal a centralized log file for a cluster of Apache servers.
C
2
star
28

chef-sudo

Cookbook to manage sudoers file
Ruby
1
star
29

revealjs_omniti_template

Template for creating OmniTI reveal.js themed presentations
JavaScript
1
star
30

openssh-securid

OpenSSH with SecurID integration
1
star
31

omniti-ms

OmniTI OmniOS package repo build scripts
Shell
1
star
32

mungo-PSGI

Perl
1
star