Skip to content

Standard JSON API Responses

jennyjenny Posts: 9
edited August 8 in Backend

There are 2 kind of responses in each API request which are Success response and Error response i will explain briefly some of our API’s responses how it looks

The main response structure have 4 keys which are
1. error_code code to indicate if there was an error
2. Success always returning true or false if the response is success will returning true otherwise will get false
3. Message it’s better to return the response message from back-end
4. data which is the main key and will have the data that should be displayed

{
    "success": true,
    "message": "User logged in successfully",
    "data": { }
}

Comments

  • jennyjenny Posts: 9
    edited August 8

    So let’s start with the below login example response , we have got the message and success out of data key and got the user object, JWT token and related relationship inside data:

    {
        "success": true,
        "message": "User logged in successfully",
        "data": {
            "user": {
                "id": 2,
                "name": "Client",
                "client_id": 1,
                "email": "[email protected]",
                "gender_label": null,
                "gender": null,
                "mobile": "123654789",
                "code_country": "00967",
                "birth_date": null,
                "avatar": "http://localhost:3000/default_image.png",
                "sms_notification": true,
                "is_mobile_verified": false,
                "otp": {
                    "otp": "8704"
                },
                "client_city": {
                    "id": 3,
                    "name_ar": "الرياض",
                    "name_en": "Riadh",
                    "name": "Riadh",
                    "status": 1,
                    "status_label": "Active",
                    "country": {
                        "id": 2,
                        "name": "Kingdub saudi Arab",
                        "code_country": "ksa",
                        "avatar": "http://localhost:3000/default_image.png",
                        "status": 1,
                        "status_label": "Active"
                    }
                },
                "client_locations": [
                    {
                        "id": 1,
                        "client_id": 1,
                        "latitude": "0.0",
                        "longitude": "0.0",
                        "address": "169 Rath Rapids",
                        "address_ar": "964 Michale Parkway",
                        "address_en": "169 Rath Rapids",
                        "building_name": "building_name",
                        "location_type": 1,
                        "location_type_label": "Home",
                        "apartment_name": null,
                        "require_permission": false,
                        "city": null,
                        "zip_code": null
                    }
                ]
            },
            "role": "client",
            "token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MiwibmFtZSI6IkNsaWVudCIsImVtYWlsIjoiY2xpZW50QGNsaWNrYXBwcy5jbyIsIm1vYmlsZSI6IjEyMzY1NDc4OSIsImltYWdlIjoiL2RlZmF1bHRfaW1hZ2UucG5nIiwiYWRtaW4iOmZhbHNlLCJpYXQiOjE1NDc5MjU0MzIsImV4cCI6MTU1MDUxNzQzMn0.4Vyjd7BG7v8AFSmGKmIs4VM2FBw3gOLn97Qdf6U4jxU"
        }
    }
    
  • jennyjenny Posts: 9

    Example with failed response

    {
        "success": false,
        "message": "Invalid email or password",
        "error_code": 1308,
        "data": {}
    }
    
    

    Example Login response using mobile number

    {
       "success": true,
       "message": "otp sent successfully",
       "data": {
           "otp": "9286"
       }
    }
    
    

    Example Login response using wrong mobile number

    {
       "success": false,
       "message": "Invalid mobile number.",
       "error_code": 1306,
       "data": {}
    }
    
    

    response

    {
       "success": true,
       "message": "otp confirmed successfully",
       "data": {
           "user": {
               "id": 8,
               "name": "mmb",
               "email": "[email protected]",
               "status": 2,
               "status_label": "Active",
               "mobile": "738422532",
               "code_country": "00967",
               "avatar": "http://localhost:3000/default_image.jpg",
               "customer_id": 3,
               "provider_id": null
           },
           "token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6OCwibmFtZSI6Im1tYiIsImVtYWlsIjoibW1iLjIyMTE3N0BnbWFpbC5jb20iLCJpYXQiOjE1NDc5NjYxMzQsImV4cCI6MTU1MDU1ODEzNH0.TLMc6owRpsOWl-al7yErWKcF7ylEGYW4ihEK_gLn5KY"
       }
    }
    
    
  • jennyjenny Posts: 9

    Let’s have some examples with main HTTP-variables which are GET, POST, PUT and DELETE
    GET response with collection of data

    {
        "success": true,
        "message": "Data found",
        "data": {
            "requests": [
                {
                    "id": 10,
                    "request_code": "8B2BD1",
                    "provider_name": "Al Marasim Ladies Salon",
                    "provider_name_ar": "Al Marasim Ladies Salon",
                    "provider_name_en": "Al Marasim Ladies Salon",
                    "service_name": "Nails & Feet",
                    "service_name_ar": "الأظافر والقدمين",
                    "service_name_en": "Nails & Feet",
                    "start_datetime": "2018-09-04 18:03:07",
                    "status_label": "Pending",
                    "status": 1,
                    "price_clinic_ksa": "46.01",
                    "price_clinic_uae": "52.66",
                    "price_demand_uae": "68.57",
                    "price_demand_ksa": "80.84",
                    "price_type": "hour",
                    "provider_avatar": "http://localhost:3000/default_image.png",
                    "provider_cover": "http://localhost:3000/default_image.png",
                    "request_redeemed": false,
                    "selected_price": 1,
                    "selected_price_label": "Sar",
                    "service_type": 1,
                    "service_type_label": "In clinic",
                    "transaction_status": 1,
                    "transaction_status_label": "Unprocessed payment"
                },
                {
                    "id": 8,
                    "request_code": "8713ED",
                    "provider_name": "Provider",
                    "provider_name_ar": "Provider",
                    "provider_name_en": "Provider",
                    "service_name": "Nails & Feet",
                    "service_name_ar": "الأظافر والقدمين",
                    "service_name_en": "Nails & Feet",
                    "start_datetime": "2018-09-04 18:03:07",
                    "status_label": "Pending",
                    "status": 1,
                    "price_clinic_ksa": "92.62",
                    "price_clinic_uae": "63.49",
                    "price_demand_uae": "4.28",
                    "price_demand_ksa": "87.9",
                    "price_type": "hour",
                    "provider_avatar": "http://localhost:3000/default_image.png",
                    "provider_cover": "http://localhost:3000/default_image.png",
                    "request_redeemed": false,
                    "selected_price": 1,
                    "selected_price_label": "Sar",
                    "service_type": 1,
                    "service_type_label": "In clinic",
                    "transaction_status": 1,
                    "transaction_status_label": "Unprocessed payment"
                }
            ],
            "pagination": {
                "current_page": 1,
                "next_page": null,
                "previous_page": null,
                "total_pages": 1,
                "per_page": 10,
                "total_entries": 5
            }
        }
    }
    
    
  • jennyjenny Posts: 9

    POST

    {
        "success": true,
        "message": "Order 766013 Code has been Submitted successfully",
        "data": {
            "request": {
                "id": 11,
                "request_code": "766013",
                "provider_name": "Provider",
                "provider_name_ar": "Provider",
                "provider_name_en": "Provider",
                "service_name": "Nails & Feet",
                "service_name_ar": "الأظافر والقدمين",
                "service_name_en": "Nails & Feet",
                "start_datetime": "2019-10-16 06:26:00",
                "status_label": "Pending",
                "status": 1,
                "price_clinic_ksa": "92.62",
                "price_clinic_uae": "63.49",
                "price_demand_uae": "4.28",
                "price_demand_ksa": "87.9",
                "price_type": "hour",
                "provider_avatar": "http://localhost:3000/default_image.png",
                "provider_cover": "http://localhost:3000/default_image.png",
                "request_redeemed": false,
                "selected_price": "sar",
                "selected_price_label": "Sar",
                "service_type": 1,
                "service_type_label": "In clinic",
                "transaction_status": 1,
                "transaction_status_label": "Unprocessed payment",
                "provider_mobile": "361234567",
                "provider_code_country": "00967",
                "payment_method_label": "Cash on delivery",
                "payment_method": 1,
                "client": {
                    "id": 1,
                    "name": "Client",
                    "user_id": 2,
                    "email": "[email protected]",
                    "mobile": "123654789",
                    "code_country": "00967",
                    "city_id": 3,
                    "city_name": "Riadh"
                },
                "description_en": "test",
                "description_ar": "اختبار",
                "submitted_at": "2019-01-19T19:31:26.629Z",
                "provider_address": null,
                "feedback": null,
                "can_give_feedback": true,
                "provider_rating": "0.0",
                "latitude": "0.0",
                "longitude": "0.0",
                "address_ar": "اختبر العنوان",
                "address_en": "test address",
                "address": "test address",
                "city": "Dubia",
                "zip_code": "325",
                "client_location": {
                    "id": 1,
                    "client_id": 1,
                    "latitude": "0.0",
                    "longitude": "0.0",
                    "address": "169 Rath Rapids",
                    "address_ar": "964 Michale Parkway",
                    "address_en": "169 Rath Rapids",
                    "building_name": "building_name",
                    "location_type": 1,
                    "location_type_label": "Home",
                    "apartment_name": null,
                    "require_permission": false,
                    "city": null,
                    "zip_code": null
                }
            }
        }
    }
    
    

    PUT

    {
        "success": true,
        "message": "Category updated successfully",
        "data": {
            "category": {
                "id": 11,
                "name": "First categpry",
                "name_ar": "فئة تجريبية",
                "name_en": "First categpry",
                "status": 1,
                "status_label": "Active",
                "sub_categories": []
            }
        }
    }
    
    

    DELETE

    {
        "success": true,
        "message": "Category deleted successfully",
        "data": {}
    }
    

    Push notification response

    {
      aps: {
        alert: {
          "loc-key":  "REQUEST_FORMAT",
          "loc-args": [@message]
        },
        sound:      "default",
        id:         @id,
        request_id:  @request_id,
        push_type:  push_type,
        payload:    @payload
      },
      pn_gcm: {
        data: {
          message: @message,
        }
      }
    }
    
  • jennyjenny Posts: 9

    Some of our message responses

    errors:
    # 10XX : Main App Errors
    '1000': 'App Server Error, please contact the admin' # Global Error
    '1001': 'Missing Headers'
    '1002': 'Missing Parameters'
    '1003': 'Invalid offset or limit'
    '1004': 'Invalid Locale'
    '1005': 'Invalid Timezone'
    '1006': 'You exceeded the limit of requests per minute, Please try again after sometime.'

    11XX : Http Errors

    '1101': 'Unauthorized'
    '1102': 'Not authorized to access'
    '1103': 'Unprocessable Entity'
    '1104': 'Authentication Failed'
    '1105': 'Not Found'
    

    12XX : Auth Erorrs

    '1201': 'Your session is expired, please login again' # Token expired
    '1202': 'Your sessions is invalid' # JWT verification error
    '1203': 'Your sessions is invalid' # Error encountered while decoding JWT token
    '1204': 'Your sessions token is invalid' # Invalid token
    '1205': 'You are Unauthorized, Please login' # You are Unauthorized, Please login
    '1206': 'Authentication Error, User Not found' # Authentication Error, User Not found
    

    13XX Session Errors

    '1301': 'Invalid Credentials'
    '1302': 'Invalid Login Type'
    '1303': 'Invalid Social Type'
    '1304': 'Login Error'
    '1305': 'You Account is disabled by the admin.'
    '1306': 'Invalid mobile number.'
    '1307': 'Wrong confirmation code! Try again.'
    '1308': 'Invalid email or password'
    '1309': 'Your account already exist in the app, please try to login.'
    '1310': 'Your request is invalid or your request time is over, please try again.'
    '1311': 'You are not authorized to access this app'
    '1312': 'An issue in the Active Directory Service, please contat the Administrator'
    '1313': 'your email still not confirmed, please confirm your email'
    '1314': 'Email link has been expired'
    '1315': 'Your account is not activated Please verify your email to activate the account'
    '1316': 'You cannot delete user until his requests been completed or cancelled'
    '1317': 'This number has already registered'
    '1318': 'Please before you login with google account first sign up'
    '1319': 'Your old mobile number is wrong'
    '1320': 'confirmation code is expired! Try again'
    '1321': 'You cannot delete provider until he completed or cancelled his requests'
    '1322': 'Your account was blocked by Admin. Please contact admin at [email protected]'
    

    data_found: 'Data found'
    no_data_found: 'No data found'
    not_found: 'Not found'
    x_not_found: '%{name} not found!'
    update_successfully: 'Updated successfully'
    x_update_successfully: '%{name} updated successfully'
    created_successfully: 'Created successfully'
    x_created_successfully: '%{name} created successfully'
    deleted_successfully: 'Deleted successfully'
    x_deleted_successfully: '%{name} deleted successfully'
    request_submitted: 'Order %{code} Code has been Submitted successfully'
    orders_not_found: 'No orders yet'

  • petersonpeterson Posts: 2

    Amazing Development pattern. But ome thing 8 would have suggested is using https codes on response call rather than just True and False on error response from the API call.

    Overall. It's amazing

  • dhtmldhtml Posts: 27

    It is very important to structure API responses well, it gives very good experience for frontend and mobile developers that have to integrate your API.

Sign In or Register to comment.