REST API Overview

Learn about EverShop REST API architecture, conventions, and best practices

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:

1. [auth]endpoint.ts - Authentication
2. [bodyParser]endpoint.ts - Body parsing
3. [validation]endpoint.ts - Validation
4. 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:

1. Create Directory Structure

   mkdir -p extensions/myExtension/src/api/createFoo
   cd extensions/myExtension/src/api/createFoo
   
2. Create route.json

   route.json

   {
     "methods": ["POST"],
     "path": "/foos",
     "access": "private"
   }
   
3. Create Middleware (optional)

   bodyParser.ts

   import bodyParser from 'body-parser';
   
   export default (request, response, next) => {
     bodyParser.json({ inflate: false })(request, response, next);
   };
   
4. 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 }
     });
   };
   
5. 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