@devleaf-labs/jarspec-server v1.0.2
Jarspec JS/TS/NodeJS Server
What is Jarspec?
The JSON API Response Specification (jarspec) is a new specification provided to lay a foundation for how JSON responses from RESTful API servers should be formatted.
You can read more about Jarspec here...
What is the Jarspec server
The Jarspec server (for NodeJS/Express TS/JS) is a library built to allow creating jarspec responses easier. The library contains methods for generating jarspec JSON as well as an express middleware method for using with expressJS.
Getting Started
You can install the jarspec client using the following commands:
# NPM
npm i @devleaf-labs/jarspec-server
# Yarn
yarn add @devleaf-labs/jarspec-server
And then use in your code as follows with ExpressJS:
// Using Javascript
const jserver = require('@devleaf-labs/jarspec-server');
const Jarspec = jserver.Jarspec;
// Using Typescript
import { Jarspec } from '@devleaf-labs/jarspec-server';
// Use middleware in express
app.use(Jarspec.expressMiddleware);
// create success route
app.get('/success', function(req, res) {
return res.jarspec.success(/*...*/);
});
// create error route
app.get('/error', function(req, res) {
return res.jarspec.error(/*...*/);
});
Alternatively, you can use jarspec on any NodeJS server as follows:
// Using Javascript
const jserver = require('@devleaf-labs/jarspec-server');
const Jarspec = jserver.Jarspec;
// Using Typescript
import { Jarspec } from '@devleaf-labs/jarspec-server';
// Create Jarspec Success
const successResponse = Jarspec.success(/*...*/);
// Create Jarspec Error
const errorResponse = Jarspec.error(/*...*/);
Note: If using jarspec on a non-Express server, you will need to remember to set the Content-Type
header and http code correctly, as the methods used above only act as builders for a Jarspec JSON variable.
API
Success
success<T>(data?: any[], id?: string): JarspecSuccessResponse;
Error
error<T>(rpcCode: gRPCStatus, message: string, id?: string, data?: any[], error: any): JarspecErrorResponse;
Express Middleware
expressMiddleware(req: any, res: any, next: any): void;
JarspecSuccessResponse
interface JarspecSuccessResponse<T = any> {
status: 'ok';
code: 200;
data: T[]|null;
id?: string;
timestamp: string;
version: '1.0.0';
}
JarspecErrorResponse
interface JarspecSuccessResponse<T = any> {
status: gRPCStatus;
code: HTTPStatus;
message: string;
data: T[]|null;
id?: string;
timestamp: string;
version: '1.0.0';
}
gRPCStatus
type gRPCStatus =
'ok'|
'invalid-argument'|
'failed-precondition'|
'out-of-range'|
'unauthenticated'|
'permission-denied'|
'not-found'|
'aborted'|
'already-exists'|
'resource-exhausted'|
'cancelled'|
'data-loss'|
'unknown'|
'internal'|
'not-implemented'|
'na'|
'unavailable'|
'deadline-exceeded';
HTTPStatus
type HTTPStatus =
200|
400|
401|
403|
404|
409|
429|
499|
500|
501|
502|
503|
504;