REST Endpoints

Available REST API endpoints in the EverShop application

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

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

const response = await fetch('http://localhost:3000/foos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Example Foo',
    description: 'This is an example foo item'
  })
});

const data = await response.json();
console.log(data);

import requests

url = 'http://localhost:3000/foos'
headers = {'Content-Type': 'application/json'}
payload = {
    'name': 'Example Foo',
    'description': 'This is an example foo item'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

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

id · number

Unique identifier (timestamp-based)

name · string

Name of the foo item

description · string

Description of the foo item

Success Response (201)

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

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

Implementation Details

route.json

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

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

Middleware

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

import bodyParser from 'body-parser';

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

Handler

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 resource

Status: Private (requires authentication)

Creating Custom Endpoints

To add your own REST endpoints, follow these steps:

1. Create Extension

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

   mkdir -p extensions/myExtension/src/api/myEndpoint
   
2. Define Route Configuration

   Create a route.json file:

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

   {
     "methods": ["GET", "POST"],
     "path": "/api/my-endpoint",
     "access": "public"
   }
   
3. 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' }
     });
   };
   
4. Register Extension

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

   {
     "system": {
       "extensions": [
         {
           "name": "myExtension",
           "resolve": "extensions/myExtension",
           "enabled": true
         }
       ]
     }
   }
   
5. 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:

GET

Use for retrieving resources:

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

POST

Use for creating new resources:

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

PUT

Use for full updates of existing resources:

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

PATCH

Use for partial updates of existing resources:

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

DELETE

Use for deleting resources:

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

Multiple Methods

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:

Validation Errors

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

// 404 Not Found
const item = findItem(id);
if (!item) {
  return response
    .status(404)
    .json({ error: 'Item not found' });
}

// 401 Unauthorized
if (!request.user) {
  return response
    .status(401)
    .json({ error: 'Authentication required' });
}

// 500 Internal Server Error
try {
  // Your logic
} catch (error) {
  console.error('Error processing request:', error);
  return response
    .status(500)
    .json({ error: 'Internal server error' });
}

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