JSON Server

To use JSON-Server, follow these steps:

1. Create a db.json or db.json5 file containing your data. Each top-level key in the JSON object represents a resource.
2. Start the server using npx json-server <filename>.

By default, the server starts at http://localhost:3000.

{
  "posts": [
    { "id": "1", "title": "a title", "views": 100 },
    { "id": "2", "title": "another title", "views": 200 }
  ],
  "comments": [
    { "id": "1", "text": "a comment about post 1", "postId": "1" }
  ],
  "profile": {
    "name": "typicode"
  }
}

npx json-server db.json

Install json-server using npm to get started with creating a mock REST API.

npm install json-server

If you are upgrading from json-server v0.x, be aware of the following breaking changes:

• ID handling: id is always a string and is auto-generated if not provided.
• Pagination: Use _per_page with _page instead of the deprecated _limit parameter.
• Relationships: Use _embed instead of _expand for including related resources.
• Request delays: The --delay CLI option has been removed. Use browser DevTools (Network tab > throttling) to simulate latency.

Embedding allows you to include related data in your API responses. The Service class uses the embed option in find and findById to perform this.

• One-to-One (Belongs To): If the related resource name is singular (e.g., author), the service looks for a foreign key like authorId on the current item and embeds the matching object from the authors collection.
• One-to-Many (Has Many): If the related resource name is plural (e.g., comments), the service looks for items in the comments collection where the foreign key (e.g., postId) matches the current item's id.

When calling createApp, you can pass an AppOptions object to customize the server behavior:

• logger (optional, boolean): Enables or disables logging.
• static (optional, string[]): An array of paths to additional directories to serve as static files. Paths can be absolute or relative to the current working directory (process.cwd()).

const options: AppOptions = {
  logger: true,
  static: ['assets', '/var/www/html']
}

Use _page and _per_page to paginate array resources.

• _per_page defaults to 10 if not specified.
• Invalid values are automatically normalized to valid ranges.

The response includes metadata about the pagination state.

GET /posts?_page=1&_per_page=25

Response Format:

{
  "first": 1,
  "prev": null,
  "next": 2,
  "last": 4,
  "pages": 4,
  "items": 100,
  "data": [
    { "id": "1", "title": "...", "views": 100 }
  ]
}

You can filter array resources using the syntax field:operator=value.

Supported operators:

• (no operator) eq: equal
• lt: less than
• lte: less than or equal
• gt: greater than
• gte: greater than or equal
• ne: not equal
• in: included in a comma-separated list
• contains: string contains (case-insensitive)
• startsWith: string starts with (case-insensitive)
• endsWith: string ends with (case-insensitive)

You can also filter by nested properties using dot notation (e.g., author.name:eq=typicode).

GET /posts?views:gt=100
GET /posts?title:eq=Hello
GET /posts?id:in=1,2,3
GET /posts?author.name:eq=typicode
GET /posts?title:contains=hello
GET /posts?title:startsWith=Hello
GET /posts?title:endsWith=world

The _where query parameter accepts a JSON object that allows for complex logical queries (like or or and) which override standard query parameters.

GET /posts?_where={"or":[{"views":{"gt":100}},{"author":{"name":{"lt":"m"}}}]}

When deleting a resource, you can use the _dependent query parameter to also delete related resources. For example, deleting a post can automatically delete its associated comments.

DELETE /posts/1?_dependent=comments

Use the _sort query parameter to sort results. Use a minus sign (-) before the field name to sort in descending order.

GET /posts?_sort=title
GET /posts?_sort=-views
GET /posts?_sort=author.name,-views

Use the _embed query parameter to include related resources in the response. For example, if posts have a relationship with comments, you can embed comments within the post object.

GET /posts?_embed=comments
GET /comments?_embed=post