RESTful API Routes
Check the module structure to learn more about the structure of EverShop modules.
EverShop RESTful are located in the api folder of each module. Bellow is an example of a page in the api folder of the catalog module:
catalog
├── api
│ ├── createProduct
│ │ ├── ... // Other middleware functions
│ │ └── route.json
│ ├── updateProduct
│ │ ├── ... // Other middleware functions
│ │ └── route.json
│ ├── createCategory
│ │ ├── ... // Other middleware functions
│ │ └── route.json
│ ├── updateCategory
│ │ ├── ... // Other middleware functions
│ │ └── route.json
│ ├── createAttribute
│ │ ├── ... // Other middleware functions
│ │ └── route.json
│ └── updateAttribute
│ │ ├── ... // Other middleware functions
│ └── route.json
api folder structure
The api folder contains the following subfolders:
global- This folder contains middleware functions that are used in all API. For example, theglobalfolder contains theauthmiddleware function that is used in all API endpoints.<apiID>- Those folders are the API endpoints. For example, thecreateProductfolder is the create product API endpoint.
The single api folder
Each api folder contains the middleware functions and the route definition for the API endpoint.
Below is an example of an api folder:
├── createProduct
│ ├── [context]bodyParser[auth].js
│ ├── saveProduct.js
│ └── route.json
The API route definition
In each api folder, there is a route.json file. This file contains the route definition for the API endpoint. For example, the route.json file of the deleteProduct API is:
{
"methods": [
"DELETE"
],
"path": "/products/:id",
"access": "private"
}
The folder name will be used as the routeId, so make sure the folder name is unique and does not contain any special characters.
Check the routing system document to learn more about the routing system.
The api authentication
In the route.json file, you can set the access property to public or private. If you set the access property to private, the API endpoint will be protected by the authentication system. Private API endpoints can only be accessed by the authenticated users (admin users).
For security reasons, if the access property is not set, the API endpoint will be treated as a private API endpoint.
The api request data validation
EverShop allows you to define the request data schema for each API endpoint. You can define the request data schema using a json file named payloadSchema.json in the api folder. For example, the createProduct API endpoint has the following request data schema:
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"short_description": {
"type": "string"
},
"url_key": {
"type": "string",
"pattern": "^\\S+$"
},
"meta_title": {
"type": "string"
},
"meta_description": {
"type": "string"
},
"meta_keywords": {
"type": "string"
},
"status": {
"type": [
"integer",
"string"
],
"enum": [
0,
1,
"0",
"1"
]
},
"sku": {
"type": "string"
},
"price": {
"type": [
"string",
"number"
],
"pattern": "^\\d+(\\.\\d{1,2})?$"
},
"weight": {
"type": [
"string",
"number"
],
"pattern": "^[0-9]+(\\.[0-9]{1,2})?$"
},
"qty": {
"type": [
"string",
"number"
],
"pattern": "^[0-9]+$"
},
"manage_stock": {
"type": [
"string",
"number"
],
"enum": [
0,
1,
"0",
"1"
]
},
"stock_availability": {
"type": [
"string",
"number"
],
"enum": [
0,
1,
"0",
"1"
]
},
"group_id": {
"type": [
"string",
"integer"
],
"pattern": "^[0-9]+$"
},
"visibility": {
"type": [
"integer",
"string"
],
"enum": [
0,
1,
"0",
"1"
]
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"attributes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attribute_code": {
"type": "string"
},
"value": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
}
}
},
"categories": {
"type": "array",
"items": {
"type": [
"string",
"integer"
],
"pattern": "^[0-9]+$"
}
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"option_name": {
"type": "string"
},
"option_type": {
"type": "string",
"enum": [
"select",
"multiselect"
]
},
"is_required": {
"type": [
"string",
"integer"
],
"enum": [
0,
1,
"0",
"1"
],
"default": 0
},
"values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"extra_price": {
"type": [
"string",
"number"
],
"pattern": "^\\d+(\\.\\d{1,2})?$"
}
}
}
}
},
"required": [
"option_name",
"option_type",
"values"
],
"additionalProperties": true
}
}
},
"required": [
"name",
"meta_title",
"url_key",
"status",
"sku",
"qty",
"price",
"weight",
"group_id",
"visibility"
],
"additionalProperties": true
}
The request data will be validated based on this schema. If the validation was failed, an error response will be sent to client.
EverShop makes use of Ajv JSON schema validator for request payload validation.
The api middleware functions
EverShop allows you to create middleware functions for each API. You can create many middleware functions as you need.
Check the middleware system document to learn more about the middleware system.
Shared middleware functions
In some cases, you may need to use the same middleware functions in multiple API. For example, you may need to use the same middleware function for the createProduct and updateProduct API. In this case, you can create a special folder createProduct+updateProduct in the api folder and put the middleware function in this folder. All middleware function in this folder will be executed in both API endpoints.
This special folder does not contain any route.json file. It only contains middleware functions.
If you have a middleware function that required for all API endpoints (both frontStore and admin panel), you can put it in the api/global.