# jigsaw-restful

> jigsaw-restful is a router component of jigsaw-rpc

Latest version **0.2.4** (published 2021-03-13) · GPL-2.0 license · 0 weekly downloads

## Install

```sh
npm install jigsaw-restful
pnpm add jigsaw-restful
yarn add jigsaw-restful
bun add jigsaw-restful
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.4 |
| Published | 2021-03-13 |
| First published | 2020-11-22 |
| Weekly downloads | 0 |
| License | GPL-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 16 |
| Unpacked size | 79.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | zhymc |
| Maintainers | zhyjs |
| Keywords | router, jigsaw |

## Links

- npm: https://www.npmjs.com/package/jigsaw-restful
- Repository: https://github.com/jigsaw-rpc/jigsaw-restful
- Homepage: https://github.com/jigsaw-rpc/jigsaw-restful#readme
- Issues: https://github.com/jigsaw-rpc/jigsaw-restful/issues
- npm.io page: https://npm.io/package/jigsaw-restful

## Dependencies (16)

- [koa](https://npm.io/package/koa.md) ^2.13.1
- [meow](https://npm.io/package/meow.md) ^9.0.0
- [debug](https://npm.io/package/debug.md) ^4.2.0
- [koa-cors](https://npm.io/package/koa-cors.md) ^0.0.16
- [@types/koa](https://npm.io/package/@types/koa.md) ^2.11.6
- [jigsaw-rpc](https://npm.io/package/jigsaw-rpc.md) ^0.2.5
- [koa-compose](https://npm.io/package/koa-compose.md) ^4.1.0
- [url-pattern](https://npm.io/package/url-pattern.md) ^1.0.3
- [validatorjs](https://npm.io/package/validatorjs.md) ^3.21.0
- [route-parser](https://npm.io/package/route-parser.md) 0.0.5
- [koa-useragent](https://npm.io/package/koa-useragent.md) ^4.0.0
- [koa-bodyparser](https://npm.io/package/koa-bodyparser.md) ^4.3.0
- [serialize-error](https://npm.io/package/serialize-error.md) ^8.0.1
- [config-style-cli](https://npm.io/package/config-style-cli.md) ^0.0.2
- [@types/validatorjs](https://npm.io/package/@types/validatorjs.md) ^3.15.0
- [tiny-typed-emitter](https://npm.io/package/tiny-typed-emitter.md) ^2.0.3

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 0.2.4 (latest) — 2021-03-13
- 0.2.2 — 2021-03-13
- 0.2.1 — 2021-03-13
- 0.2.0 — 2021-03-13
- 0.1.6 — 2021-03-13
- 0.1.5 — 2021-03-10
- 0.1.4 — 2021-03-10
- 0.1.3 — 2021-03-10
- 0.1.2 — 2021-03-10
- 0.1.1 — 2021-03-06
- 0.1.0 — 2021-03-06
- 0.0.11 — 2021-02-24
- 0.0.10 — 2021-02-24
- 0.0.9 — 2021-02-24
- 0.0.8 — 2021-02-24
- … 34 more at https://npm.io/package/jigsaw-restful/versions

## README

# Jigsaw-Restful

jigsaw-restful is an API framework written in TypeScript, it can be used to design stable HTTP APIs through Jigsaws.

## Install

in a npm project folder, run:
```
npm install jigsaw-restful --save
```

## Easy-to-start Example

api.js
```js
const { RPC } = require("jigsaw-rpc");
const Restful = require("jigsaw-restful");
const router = new Restful.Router();

router.get("/v1/test/res",{
    public:true,
    desc:"This API can get result",
    return:"string",
    vali:{
        str:"required"
    }
},async (ctx,next)=>{
    ctx.result.hello = ctx.data.str;
    await next();
});

const jg = RPC.GetJigsaw({name:"testjigsaw"});
jg.use(router.router());

```

then try this:

app.js
```js
const { RPC } = require("jigsaw-rpc");

const invoker = RPC.GetJigsaw();

invoker.send("test:<get>/v1/test/res",{
    str:"world!"
}).then(console.log);

// will get a "hello":"world";
```

## Advanced Example

endpoint.js
```js
const { RPC } = require("jigsaw-rpc");
const adapter = new Restful.KoaAdapter(RPC.GetJigsaw());

const koa = new Koa();
koa.use(adapter.koa());
koa.listen(80);

```

then try access by HTTP client:


```
GET http://127.0.0.1/v1/test/res?path=testjigsaw
body: {str:"world!"}
```

You will get the HTTP Response:

```json
{
	"error": false,
	"code": 0,
	"httpcode": 200,
	"message": "API invoked successfully",
	"detail": "",
	"type": "object",
	"data": {"hello":"world"}
}
```

if you don't follow the rules of validation like:
```
GET http://127.0.0.1/v1/test/res?path=testjigsaw
body: {}
```

will get a HTTP 400 Bad Request like this:

```json
{
	"error": true,
	"code": 9005,
	"httpcode": 400,
	"message": "Your request format isn't correct.",
	"detail": {
		"str": [
			"The str field is required."
		]
	},
	"type": "object",
	"data": null
}
```

# GET = POST

some HTTP-Client like ``axios`` don't support GET request with a body, so in Jigsaw-Restful design, 

GET method is same as POST method to get a information of resource.

PUT method is used to create a resource ,

PATCH method is used to modify a resource ,

and DELETE method is used to delete a resource.

# API Map

you can review all of apis you provide easily by:
```js
jg.use(router.secretAPIMap());
```

the complete api.js is like:
```js
const { RPC } = require("jigsaw-rpc");
const Restful = require("jigsaw-restful");
const router = new Restful.Router();

router.get("/v1/test/res",{
    public:true,
    desc:"This API can get result",
    return:"string",
    vali:{
        str:"required"
    }
},async (ctx,next)=>{
    ctx.result.hello = ctx.data.str;
    await next();
});

const jg = RPC.GetJigsaw({name:"testjigsaw"});
jg.use(router.secretAPIMap());
jg.use(router.router());
```

if you have already started the endpoint.js

you can access the API Map by HTTP Client (eg. browser).

```
GET http://127.0.0.1/apimap/?path=testjigsaw
```

and get this response:

```json
{
	"error": true,
	"code": 9005,
	"httpcode": 400,
	"message": "Your request format isn't correct.",
	"detail": {
		"/v1/test/res": {
			"desc": {
				"get": "This API can get result",
				"post": "This API can get result"
			},
			"return": "string",
			"method": {
				"get": {
					"str": "required"
				},
				"post": {
					"str": "required"
				}
			}
		}
	},
	"type": "object",
	"data": null
}
```

---
_Source: https://npm.io/package/jigsaw-restful · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._