Table of Contents
About
Recognition, this project wouldn't be here with out the great json-server
. I thought to myself that JSON was a little verbose. So I created yaml-server
so you can have a Mock REST API based on a YAML file instead.
yaml-server
is a command line tool that create a REST server based on a YAML file.
Features
-
RESTful API Do HTTP requests towards a Mock API using GET, PUT, POST and DELETE created off of a
db.yml
file. -
Filter your GET calls with query parameters
page
andpageSize
, example:/products?page=1&pageSize=10 -
JSON support, yes you can have your database in JSON as well. All you need is to specify the
--dialect
argument like so:npx yaml-server --dialect=jsonThe above will look after a
db.json
file at the root. You override where it looks for this if you specify--database
like for example:npx yaml-server --dialect=json --database ./db/db.jsonAbove you need to ensure the
db.json
is located in sub directorydb
as seen from the root. -
Create new resource, make a POST call with the following format
/<new resource>/new
, example:/kittens/newEnsure you have a payload as well, looking like for example
{ title: 'paw paw' }
-
Sorting, by order and key, you can sort a resource response using query parameters
sortOrder
andsortKey
. Assume we have the resource/kittens
where one kitten object looks like so{ id: 1, name: 'paws' }
and the entire resource looks like so:id: 1name: 'paws'id: 2name: 'alpha paw'Use sorting by appending
sortOrder
andsortKey
like below:/kittens?sortOrder=ASC&sortKey=nameThis would give the response:
id: 2name: 'alpha paw'id: 1name: 'paws' -
browser autostart, the Browser auto starts at
http://locallhost:<selected port>/info
. Should you not wish to have that behavior, you can shut it off like so:npx yaml-server --autoStart=off -
Static file server
By default a static file server is starting up to host your files at root directory. You can change that by specifying
--static
. Here's how you would do that:npx yaml-server --static=publicThe above would start a static file server from the sub folder
public
. -
Hot reload
The server will restart if you make changes to your database file. No need for closing and starting the server after a database change. Should you not wish that behavior, you can shut it off with:
npx yaml-server --hotReload=off
Install
Either install it globally with:
npm install -g yaml-server
OR use NPX
npx yaml-server --port 3000 --database ./db.yml
Run
-
Create a
db.yml
. -
Give
db.yml
an example content, for example:products:- id: 1name: tomato- id: 2name: lettuceorders:- id: 1name: order1- id: 2name: order2 -
There are two ways to start:
- Quick start, run
npx yaml-server
, this will start a server onhttp://localhost:3000
and base it off adb.yml
at the project root that you created. - With parameters, You can also configure like so
npx yaml-server --port 8000 --database ./db/mydb.yml
(If you place db file under./db/mydb.yml
)
- Quick start, run
See your routes
Open up a browser and navigate to http://localhost:<your port>/info
. Default port is 3000
, if you specified port use that as port instead.
The page at route http://localhost:<port>/info
will tell you what routes and operations are available. Here's a typical response for the default page:
Welcome to YAML Server Routes available are: GET /products GET /products/:id PUT /products DELETE /products/:id GET /orders GET /orders/:id PUT /orders DELETE /orders/:id
Routes
Routes are created from a YAML file. The default value is db.yml
. You can name it whatever you want though.
Routes are first level elements. Consider the following example file:
# db.ymlproducts: - id: 1 name: tomato - id: 2 name: lettuceorders: - id: 1 name: order1 - id: 2 name: order2
This will produce routes /products
, /orders
. Below is a table of supported operations with products
as example resource. The same operations are also supports for orders/
.
VERB | Route | Input | Output |
---|---|---|---|
GET | /products | None | Array |
GET | /products/:id | e.g 3 | Object |
POST | /products | object | Created object |
PUT | /products | object | Updated object |
DELETE | /products/:id | e.g 3 | Deleted object |