REST API Overview - My EverShop App

Introduction

EverShop’s REST API allows you to create custom endpoints for your e-commerce application. The API follows a modular architecture where endpoints are defined within extensions using a declarative routing system.

API Architecture

REST endpoints in EverShop are organized within extensions and follow a specific directory structure:

extensions/[name]/src/api/[endpoint]/
├── route.json                    # Route configuration
├── [middleware]endpoint.ts       # Middleware handlers (optional)
└── endpoint.ts                   # Main endpoint handler

Key Components

Route Configuration

Declarative JSON file defining HTTP methods, path, and access control

Middleware Chain

Optional middleware functions that run before the main endpoint handler

Endpoint Handler

Main function that processes the request and returns a response

TypeScript Support

Full TypeScript support with EverShop request/response types

Route Configuration

Every endpoint requires a route.json file that defines its routing configuration:

route.json

{
  "methods": ["POST"],
  "path": "/foos",
  "access": "private"
}

Configuration Fields

methods

string[]

required

Array of allowed HTTP methods. Supported values: GET, POST, PUT, PATCH, DELETE

"methods": ["GET", "POST"]

path

string

required

The URL path where the endpoint will be accessible. Can include path parameters.

"path": "/api/products/:id"

access

string

required

Access control level for the endpoint.

public - Accessible without authentication
private - Requires authentication

"access": "private"

Request/Response Types

EverShop provides TypeScript types for handling HTTP requests and responses:

import { EvershopRequest, EvershopResponse } from '@evershop/evershop';

export default (
  request: EvershopRequest,
  response: EvershopResponse,
  next
) => {
  // Your endpoint logic
};

EvershopRequest

Extends Express.js Request with additional properties:

body

object

Parsed request body (requires bodyParser middleware)

params

object

URL path parameters

query

object

URL query string parameters

headers

object

HTTP request headers

EvershopResponse

Extends Express.js Response with standard methods:

status(code)

function

Sets the HTTP status code

json(data)

function

Sends a JSON response

send(data)

function

Sends a generic response

Middleware Pattern

Middleware functions run before the main endpoint handler. They are named using the pattern [middlewareName]endpoint.ts:

bodyParser.ts

import bodyParser from 'body-parser';

export default (request, response, next) => {
  bodyParser.json({ inflate: false })(request, response, next);
};

[bodyParser]createFoo.ts

import { EvershopRequest, EvershopResponse } from '@evershop/evershop';

export default (request: EvershopRequest, response: EvershopResponse, next) => {
  const { name, description } = request.body;

  if (!name || !description) {
    return response
      .status(400)
      .json({ error: 'Name and description are required' });
  }

  // Create the new resource
  const newFoo = {
    id: Date.now(),
    name,
    description
  };

  response.status(201).json({
    success: true,
    data: { foo: newFoo }
  });
};

Middleware Execution Order

Middleware files are executed in alphabetical order based on the middleware name in square brackets:

[auth]endpoint.ts - Authentication
[bodyParser]endpoint.ts - Body parsing
[validation]endpoint.ts - Validation
endpoint.ts - Main handler

Response Conventions

Success Response

For successful operations, return a structured JSON response:

{
  "success": true,
  "data": {
    "foo": {
      "id": 1692345678901,
      "name": "Example Foo",
      "description": "This is an example"
    }
  }
}

Error Response

For errors, include descriptive error messages:

{
  "error": "Name and description are required"
}

HTTP Status Codes

Follow standard HTTP status code conventions:

Status Code	Use Case
200	Successful GET, PUT, or PATCH
201	Successful POST (resource created)
204	Successful DELETE (no content)
400	Bad Request (validation error)
401	Unauthorized (authentication required)
403	Forbidden (insufficient permissions)
404	Not Found
500	Internal Server Error

Best Practices

Use TypeScript

Always use TypeScript for type safety and better IDE support:

interface FooInput {
  name: string;
  description: string;
}

export default (request: EvershopRequest, response: EvershopResponse) => {
  const { name, description } = request.body as FooInput;
  // ...
};

Validate Input

Always validate request data before processing:

if (!name || !description) {
  return response
    .status(400)
    .json({ error: 'Name and description are required' });
}

Use Appropriate Status Codes

Return the correct HTTP status code for each scenario:

201 for resource creation
400 for validation errors
404 for not found

Structure Responses Consistently

Use a consistent response format across all endpoints:

// Success
response.status(200).json({
  success: true,
  data: { /* payload */ }
});

// Error
response.status(400).json({
  error: "Error message"
});

Separate Middleware Logic

Keep concerns separated by using dedicated middleware files:

Authentication in [auth]endpoint.ts
Validation in [validation]endpoint.ts
Body parsing in [bodyParser]endpoint.ts

Example: Complete Endpoint

Here’s a complete example of creating a REST endpoint:

Create Directory Structure

mkdir -p extensions/myExtension/src/api/createFoo
cd extensions/myExtension/src/api/createFoo

Create route.json

route.json

{
  "methods": ["POST"],
  "path": "/foos",
  "access": "private"
}

Create Middleware (optional)

bodyParser.ts

import bodyParser from 'body-parser';

export default (request, response, next) => {
  bodyParser.json({ inflate: false })(request, response, next);
};

Create Endpoint Handler

[bodyParser]createFoo.ts

import { EvershopRequest, EvershopResponse } from '@evershop/evershop';

export default (request: EvershopRequest, response: EvershopResponse) => {
  const { name, description } = request.body;

  if (!name || !description) {
    return response
      .status(400)
      .json({ error: 'Name and description are required' });
  }

  const newFoo = {
    id: Date.now(),
    name,
    description
  };

  console.log('Creating new foo:', newFoo);

  response.status(201).json({
    success: true,
    data: { foo: newFoo }
  });
};

Test the Endpoint

curl -X POST http://localhost:3000/foos \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Foo", "description": "A test item"}'

Next Steps

View Endpoints

Browse available REST endpoints in this application

GraphQL API

Learn about the GraphQL API as an alternative

Creating Extensions

Learn how to create custom extensions

API Endpoints Guide

Step-by-step guide to creating API endpoints

GraphQL API

REST API

Configuration

Documentation Index

​Introduction

​API Architecture

​Key Components

Route Configuration

Middleware Chain

Endpoint Handler

TypeScript Support

​Route Configuration

​Configuration Fields

​Request/Response Types

​EvershopRequest

​EvershopResponse

​Middleware Pattern

​Middleware Execution Order

​Response Conventions

​Success Response

​Error Response

​HTTP Status Codes

​Best Practices

​Example: Complete Endpoint

​Next Steps

View Endpoints

GraphQL API

Creating Extensions

API Endpoints Guide

Build docs developers (and LLMs) love

Introduction

API Architecture

Key Components

Route Configuration

Configuration Fields

Request/Response Types

EvershopRequest

EvershopResponse

Middleware Pattern

Middleware Execution Order

Response Conventions

Success Response

Error Response

HTTP Status Codes

Best Practices

Example: Complete Endpoint

Next Steps