Skip to main content

API Overview

Introduction

EverShop is built on a modern API-first architecture, providing developers with powerful and flexible ways to interact with the platform. This approach enables seamless integration with various frontend technologies, third-party systems, and custom applications.

EverShop offers two complementary API approaches:

  1. RESTful API - For creating, updating, and deleting resources
  2. GraphQL API - For efficient querying of resources with precise control over returned data

This dual approach combines the simplicity and standardization of REST with the flexibility and efficiency of GraphQL.

info

For detailed information on API route configuration, refer to our API Routes documentation.

info

To learn about EverShop's GraphQL implementation, visit our GraphQL API documentation.

API Architecture

REST API

The REST API follows standard RESTful principles with resource-oriented URLs and appropriate HTTP methods. This API is ideal for:

  • Creating, updating, and deleting resources
  • Standard CRUD operations
  • Familiar, predictable patterns for developers

GraphQL API

The GraphQL API provides a single endpoint that accepts complex queries. This API is ideal for:

  • Retrieving exactly the data you need, no more or less
  • Reducing the number of network requests
  • Complex data requirements with nested relationships

Content Types

All API requests and responses use the JSON format. The content type for both requests and responses is application/json.

When sending data to the API, include the following header:

Content-Type: application/json

Authentication

EverShop currently implements cookie-based authentication. To authenticate:

  1. Call the admin login API endpoint
  2. The API returns a session cookie
  3. Include this cookie in all subsequent requests requiring authentication

Public Endpoints

Some API endpoints are publicly accessible without authentication. These endpoints are identified by the access property set to public in their respective route.json files. No authentication credentials are required for these endpoints.

HTTP Methods

EverShop's REST API uses standard HTTP methods to perform different actions on resources:

MethodDescriptionIdempotent
GETRetrieves resources without modifying themYes
POSTCreates new resourcesNo
PATCHUpdates resources with partial dataYes
DELETERemoves resourcesYes

Idempotency

Idempotent methods can be called multiple times with the same effect as calling them once. This is important for reliability and error recovery.

Response Codes

EverShop uses standard HTTP status codes to indicate the result of API requests:

Success Codes

CodeDescriptionCommon Use Cases
200OKSuccessful GET, PATCH, or DELETE
201CreatedSuccessful POST that created a resource

Client Error Codes

CodeDescriptionCommon Use Cases
400Bad RequestInvalid input or missing parameters
401UnauthorizedAuthentication failure
403ForbiddenAuthenticated but insufficient permissions
404Not FoundResource doesn't exist
405Method Not AllowedHTTP method not supported for endpoint
409ConflictResource state conflict (e.g., duplicate)

Server Error Codes

CodeDescriptionCommon Use Cases
500Internal Server ErrorUnexpected server-side errors

Error Handling

When an API request fails, the response will include an error object with details about the failure:

{
"error": {
"status": 500,
"message": "Detailed error message"
}
}

The error object contains:

  • status: The HTTP status code
  • message: A human-readable description of the error

Pagination

For endpoints that return collections of resources, EverShop implements pagination to manage response size:

{
"data": [...],
"links": {
"first": "/api/resource?page=1",
"last": "/api/resource?page=5",
"prev": "/api/resource?page=2",
"next": "/api/resource?page=4"
},
"meta": {
"current_page": 3,
"from": 41,
"last_page": 5,
"path": "/api/resource",
"per_page": 20,
"to": 60,
"total": 100
}
}

Pagination Parameters

ParameterDescriptionDefault
pagePage number to retrieve1
limitNumber of items per page20

Best Practices

  1. Use HTTPS - Always use secure connections for API requests
  2. Limit Request Volume - Implement proper caching and throttling mechanisms
  3. Handle Rate Limiting - Be prepared to handle 429 Too Many Requests responses
  4. Validate Input - Always validate request data before sending to the API
  5. Handle Errors Gracefully - Implement proper error handling in your application