Skip to main content

​
Overview

The ServITech Backend API uses a consistent JSON response format for all endpoints. This standardization makes it easier to handle responses in your application and provides a predictable structure for both success and error cases. All responses are handled by the ApiResponse class located at app/Http/Responses/ApiResponse.php.

​
Success Response Structure

All successful API responses follow this structure: 
{
  "status": 200,
  "message": "Success message",
  "data": {
    // Response data object or array
  }
}

​
Success Response Fields

FieldTypeDescription
statusintegerHTTP status code (200, 201, etc.)
messagestringLocalized success message
dataobject/arrayResponse data (empty object {} if no data)

​
Success Response Example

{
  "status": 200,
  "message": "User logged in successfully",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "role": "user"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expires_in": 3600
  }
}

​
Error Response Structure

All error responses follow this structure: 
{
  "status": 400,
  "message": "Error message",
  "errors": {
    // Error details object
  }
}

​
Error Response Fields

FieldTypeDescription
statusintegerHTTP error status code (400, 401, 404, 500, etc.)
messagestringLocalized error message
errorsobjectDetailed error information (empty object {} if no details)

​
Error Response Examples

{
  "status": 400,
  "message": "The given data was invalid",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password must be at least 8 characters."
    ]
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests.

​
Success Codes

CodeNameUsage
200OKRequest successful, data returned
201CreatedResource successfully created

​
Client Error Codes

CodeNameUsage
400Bad RequestInvalid request data or validation error
401UnauthorizedAuthentication required or failed
403ForbiddenAuthenticated but not authorized
404Not FoundResource not found

​
Server Error Codes

CodeNameUsage
500Internal Server ErrorUnexpected server error

​
Localized Messages

All message fields in responses are localized based on the request’s language preference. The API supports:
  • Spanish (es) - Default
  • English (en) - Fallback
To specify your preferred language, include the Accept-Language header: 
curl -X POST "http://localhost:8000/api/auth/login" \
  -H "Accept-Language: en" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123"
  }'

​
Handling Responses

Here are examples of how to handle API responses in different programming languages: 
fetch('http://localhost:8000/api/articles', {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Accept-Language': 'en'
  }
})
  .then(response => response.json())
  .then(result => {
    if (result.status === 200) {
      // Success - access data
      console.log('Articles:', result.data.articles);
    } else {
      // Error - handle errors
      console.error('Error:', result.message);
      console.error('Details:', result.errors);
    }
  })
  .catch(error => {
    console.error('Network error:', error);
  });

​
Common Response Patterns

​
Empty Data Response

When there is no data to return (e.g., after deletion), the data field contains an empty object: 
{
  "status": 200,
  "message": "Article deleted successfully",
  "data": {}
}

​
List Responses

When returning multiple items, they are wrapped in a named array within the data object: 
{
  "status": 200,
  "message": "Articles retrieved successfully",
  "data": {
    "articles": [
      { "id": 1, "title": "Article 1" },
      { "id": 2, "title": "Article 2" }
    ]
  }
}

​
Single Resource Responses

When returning a single resource, it is wrapped in a named object within the data object: 
{
  "status": 200,
  "message": "Article retrieved successfully",
  "data": {
    "article": {
      "id": 1,
      "title": "Article Title",
      "content": "Article content..."
    }
  }
}

​
Best Practices

Always check the status field to determine if the request was successful.
Use the message field to display user-friendly feedback.
Parse the errors object for detailed validation or error information.
Handle network errors separately from API errors in your application.
The API returns consistent response structures even during exceptions, making error handling predictable and straightforward.

Build docs developers (and LLMs) love

Get started for freeTalk to us