Responses

Canteen's API returns standardized JSON responses to indicate the outcome of each request. The API follows RESTful principles, using conventional HTTP status codes to communicate success or failure.

Response Structure

Each response from the API follows this format:

{
  "success": true,
  "message": "Request was successful.",
  "data": { ... }
}

Key	Type	Description
success	bool	Indicates whether the request was successful (true) or failed (false).
message	string	Provides a human-readable explanation of the response.
data	object	Contains the actual response data (if applicable).

Example: Successful Response

Request:

curl -X GET https://your-org-uuid.canteenweb.com/api/v1/admin/orders \
  -H "Authorization: Bearer your-access-token"

Response:

{
  "success": true,
  "message": "Orders retrieved successfully.",
  "data": [
    {
      "id": 1,
      "amount": 500,
      "status": "completed",
      "created_at": "2024-02-12T10:00:00Z"
    }
  ]
}

Error Responses

If a request fails, the response will include an appropriate HTTP status code along with an error message.

Common Error Responses

HTTP Status	Meaning	Example Response
400 Bad Request	The request was malformed or missing required parameters.	{ "success": false, "message": "Invalid request data." }
401 Unauthorized	The request is missing authentication or has an invalid token.	{ "success": false, "message": "Unauthorized. Please provide a valid token." }
403 Forbidden	The request is authenticated but lacks necessary permissions.	{ "success": false, "message": "You do not have permission to access this resource." }
404 Not Found	The requested resource does not exist.	{ "success": false, "message": "Resource not found." }
422 Unprocessable Entity	Validation errors occurred in the request data.	{ "success": false, "message": "Validation failed.", "errors": { "email": ["The email field is required."] } }
500 Internal Server Error	A server error occurred while processing the request.	{ "success": false, "message": "An unexpected error occurred." }

Validation Errors

When a request fails due to validation errors (e.g., missing fields), the response will include an errors object detailing the issues.

Example: Validation Error (422 Unprocessable Entity)

{
  "success": false,
  "message": "Validation failed.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Each field in errors contains an array of error messages related to that specific field.

Handling API Responses

To ensure a smooth integration, handle API responses by checking the success flag and interpreting the response accordingly.

Example: Handling Responses in JavaScript

fetch('https://your-org-uuid.canteenweb.com/api/v1/admin/orders', {
  headers: {
    'Authorization': 'Bearer your-access-token'
  }
})
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('orders:', data.data);
    } else {
      console.error('Error:', data.message);
    }
  })
  .catch(error => console.error('Request failed:', error));