Standard JSON API response format

MaJeD BoJaN
Jan 20 · 6 min read

Recently one of my friend asked me if there is any standard response we follow for API response, this quotation asked too much from beginner developers especially those are new in term of API

I was really interested by this question as I have to design a JSON API everyday and found myself wondering if they were any standards defining a response format, i started searching about standard JSON format but i found there is no standard Not only within JSON itself, but in terms of how to use it for RESTful applications or anything else of the sort. Everybody does it differently.
So i decided to explain what the standard we are following in our company, we are writing API’s in rails framework and returning response in JSON format.

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": { }
}

So let’s start with the bellow 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": "client@clickapps.co",
"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"
}
}

Example with field 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": "mmb.221177@gmail.com",
"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"
}
}

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
}
}
}

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": "client@clickapps.co",
"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,
}
}
}

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 support@laancare.com'
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'

Consultation

This is not global standard format for RESTful API’s but we follow it in most our applications in our company if you liked feel free to design your API’s as same we have done above if you have any addition please feel free tell us.

MaJeD BoJaN

Written by

Self-Taught Back-End Developer || Aspiring Full-Stack Developer || Tech enthusiast || Big fans of FC. Barcelona.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade