API Standard

Header

Key Value Remark
Os-Type ios / android Required
App-Version 1.0.0 Required
Api-Version 1 Required
Accept application/json Required
Authorization Bearer {token} For API with Authentication
Language en / cn For Apps with multilingual (Optional))
Timezone +8 For Apps required to handle different timezone (Optional)

Request Method

Method Description
POST To create a resource
GET To read a resource or collection of resources
PUT To update/modify/replace a resource
DELETE To destroy a resource

Request Body

  • Body Parameters (multipart/form-data)

Response Body

{
    'status': true,
    'code': 400000,
    'message': 'Category created successfully',
    'data': [] / {},
    'debug': null
}


Status

  • Must be boolean
  • False = invalid/failure
  • True = valid/success


Message

  • Must be string
  • For apps to toast message


Code

  • Define based on project
  • will come out a list of basic function code
  • Must be integer
  • Must be 6 digits
  • Starting point will be 100000
  • Debug is for debug use
  • Pos 1-2: module (eg. user)
  • Pos 3-4: function (eg. add / edit)
  • Pos 5-6: (eg. 00 success, 01 validation error, 02 others error)


Data

  • Must be object {} or array [] except empty
  • To be in null when it is empty
  • Single = start with {}
  • Multiple = start with []

Pagination

  • Skip Take

Exception Handling

  • To handle exception by throw BadRequestException
  • Any other handling may do it manually in Handler.php under app/Exceptions
if($something_happen){
    throw (new BadRequestException("New Version Available", 409))
        ->withErrorKey(ResponseCode::FORCE_UPDATE, "FORCE_UPDATE")
        ->withValue($anything);
}
HTTP Code Apps Exception Message
400 InvalidRequestException eg. Insufficient Credit
(Message from backend)
401 UnauthorizedException Unauthorized
404 NotFoundException Not Found
409 ForceUpdateException New Version Available
422 ValidationException eg: The name field is required
(First Error Message in error list)
429 TooManyRequestException Too Many Attempts
500 InternalServerErrorException Server Error
503 MaintenanceException Service Unavailable
(Apps to show under maintenance page)

Tools

  • Postman
  • Apifox