REST Endpoints - My EverShop App

Overview

This page documents all available REST API endpoints in the application. Endpoints are organized by extension.

All private endpoints require authentication. Public endpoints can be accessed without credentials.

Sample Extension

The sample extension provides example endpoints demonstrating EverShop’s REST API patterns.

Create Foo

Creates a new Foo resource.

curl -X POST http://localhost:3000/foos \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Foo",
    "description": "This is an example foo item"
  }'

Endpoint Details

method

string

default:"POST"

HTTP Method

path

string

default:"/foos"

Endpoint URL path

access

string

default:"private"

Requires authentication

Request Body

name

string

required

The name of the foo item

"name": "Example Foo"

description

string

required

A description of the foo item

"description": "This is an example foo item"

Response

success

boolean

Indicates if the operation was successful

data

object

Contains the created resource

Show data properties

foo

object

The created foo object

Show foo properties

number

Unique identifier (timestamp-based)

name

string

Name of the foo item

description

string

Description of the foo item

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

Implementation Details

route.json
Middleware
Handler

extensions/sample/src/api/createFoo/route.json

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

extensions/sample/src/api/createFoo/bodyParser.ts

import bodyParser from 'body-parser';

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

extensions/sample/src/api/createFoo/[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 foo item
  const newFoo = {
    id: Date.now(),
    name,
    description
  };

  // Simulate saving to a database
  console.log('Creating new foo:', newFoo);

  // Respond with the created foo item
  response.status(201).json({
    success: true,
    data: {
      foo: newFoo
    }
  });
};

Endpoint Reference

All available endpoints organized by extension:

Sample Extension

POST /foos - Create a new Foo resourceStatus: Private (requires authentication)

Creating Custom Endpoints

To add your own REST endpoints, follow these steps:

Create Extension

Create a new extension if you don’t have one:

mkdir -p extensions/myExtension/src/api/myEndpoint

Define Route Configuration

Create a route.json file:

extensions/myExtension/src/api/myEndpoint/route.json

{
  "methods": ["GET", "POST"],
  "path": "/api/my-endpoint",
  "access": "public"
}

Implement Handler

Create your endpoint handler:

extensions/myExtension/src/api/myEndpoint/myEndpoint.ts

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

export default (request: EvershopRequest, response: EvershopResponse) => {
  response.status(200).json({
    success: true,
    data: { message: 'Hello from my endpoint' }
  });
};

Ensure your extension is registered in config/default.json:

{
  "system": {
    "extensions": [
      {
        "name": "myExtension",
        "resolve": "extensions/myExtension",
        "enabled": true
      }
    ]
  }
}

Test Your Endpoint

Start the development server and test:

npm run dev
curl http://localhost:3000/api/my-endpoint

Authentication

Endpoints marked as "access": "private" require authentication. The authentication mechanism depends on your EverShop configuration.

For development and testing, you may want to temporarily set endpoints to "access": "public". Remember to change them back to "private" before deploying to production.

HTTP Methods

Supported HTTP methods for REST endpoints:

Use for retrieving resources:

{
  "methods": ["GET"],
  "path": "/api/items/:id",
  "access": "public"
}

Use for creating new resources:

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

Use for full updates of existing resources:

{
  "methods": ["PUT"],
  "path": "/api/items/:id",
  "access": "private"
}

Use for partial updates of existing resources:

{
  "methods": ["PATCH"],
  "path": "/api/items/:id",
  "access": "private"
}

Use for deleting resources:

{
  "methods": ["DELETE"],
  "path": "/api/items/:id",
  "access": "private"
}

Support multiple methods on the same endpoint:

{
  "methods": ["GET", "POST", "PUT", "DELETE"],
  "path": "/api/items",
  "access": "private"
}

Handle different methods in your handler:

export default (request: EvershopRequest, response: EvershopResponse) => {
  switch (request.method) {
    case 'GET':
      // Handle GET
      break;
    case 'POST':
      // Handle POST
      break;
    case 'PUT':
      // Handle PUT
      break;
    case 'DELETE':
      // Handle DELETE
      break;
  }
};

Error Handling

Best practices for error handling in REST endpoints:

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

Next Steps

REST API Overview

Learn about REST API conventions and best practices

GraphQL API

Explore the GraphQL API as an alternative

API Endpoints Guide

Step-by-step guide to creating endpoints

Extensions

Learn about available extensions

GraphQL API

REST API

Configuration

Documentation Index

​Overview

​Sample Extension

​Create Foo

​Endpoint Details

​Request Body

​Response

​Implementation Details

​Endpoint Reference

Sample Extension

​Creating Custom Endpoints

​Authentication

​HTTP Methods

​Error Handling

​Next Steps

REST API Overview

GraphQL API

API Endpoints Guide

Extensions

Build docs developers (and LLMs) love

Overview

Sample Extension

Create Foo

Endpoint Details

Request Body

Response

Implementation Details

Endpoint Reference

Creating Custom Endpoints

Authentication

HTTP Methods

Error Handling

Next Steps