Dear Backender (A Rude Open Letter)
Dear backend developer…
This post is the first of a series about the struggle I as an Android applications developer must endure when working with backend developers, designers or other people involved in building a mobile application.
It will contain some points you might not be aware of and some things you can do to make the mobile application developer’s life easier or at the very least not make it harder than it should.
Disclaimer: My personal opinions and preferences might be included in these articles and you’re welcome to correct any incorrect points in the comments below.
If you are a mobile application developer you might also find something useful here especially if you’re just beginning.
So to start, this first article is dedicated to people who write APIs for mobile applications, You the backender and me the app developer are starting from scratch and no previous API exists.
The points here mainly apply to building mobile applications for Android using Java as the programming language.
I’ll be talking about APIs that return structured JSON data.
For God’s Sake: Use a Framework
Even if you’re very good with what you do, using a framework will greatly reduce the effort needed to finish the API (your business not mine) and more importantly to make your API responses more consistent with each other.
If some of your API responses return a JSON object representing some data entity then you better return this entity in the exact same structure in all the responses. Why? because we do parsing for objects using specific classes and the parsing code for data of type User for example is always the same. For example sending two responses like this is very annoying
{
"status":200,
"user":{
"id":1,
"name":"John"
}
}
{
"status":200,
"user":{
"user_id":1,
"name":"John"
}
}
Since you’re not using a framework or even a model then you might return same values with different keys, and whenever you need to modify the key you’ll end up searching all of your scripts for that key and you’ll probably forget to change some.
For the responses above to work we have to check for both id and user_id which is ugly and unnecessary.
Think about the future of the API you’re writing and try not to get the next developer (or future you) to curse each line of code.
If you have an API to return list of my friends (type: User) and another API that returns feeds or posts where each entry has user information then you should return the user object as a child object inside the post item and it should have the exact same structure of a user object returned by the friends API
Friends API Response
{
"status":200,
"data":[
{
"id":1,
"name":"John"
},
{
"id":2,
"name":"Jane"
}
]
}
Feeds API Response – The Good
{
"status":200,
"data":[
{
"id":1201,
"title":"Dear Backender",
"author":{
"id":1,
"name":"John"
}
},
{
"id":1202,
"title":"Dear Designer",
"author":{
"id":1,
"name":"John"
}
}
]
}
Feeds API Response – The Bad
{
"status":200,
"data":[
{
"id":1201,
"title":"Dear Backender",
"author_id":1,
"author_name":"John"
},
{
"id":1202,
"title":"Dear Designer",
"author_id":1,
"author_name":"John"
}
]
}
Why? to re-use the same User parsing code.
In case you’ve written very few APIs then I encourage you to see how other public APIs work and how they are organized. You can learn alot from Google, Facebook or any other APIs.
As for a good framework, in case you’re writing PHP then you might want to check Laravel.
Status Codes
Whether it’s a string or an integer, you should always return a status code of some sort. Otherwise the API client will not be able to know if the request was successfully executed on the server or not.
Whether you decide to return the status code inside the JSON body or response header always try to keep the number of status codes to minimum, sit with the app developer and agree on the status codes needed and what each one means.
Keep in mind that the app developer is probably using a central method that pre-processes ALL responses, a method that “peels” the response and gets top level information like status codes, errors and probably even the JSON data object returned within the response.
Error Messages/Responses
Try to return error messages using a specific constant key in the JSON response.
Don’t return an error if I request page 999 and you only have data up to page 5, instead return an empty JSON array. If you return an error then the app will probably think the request is malformed or invalid. Let ME handle reaching end of the results on my own. Maybe I don’t want to display a dialog or toast (Yaaaay you know Android). If you can include pagination information with the response (current page, total pages) that would be great. but If you can’t then just return an empty array.
Server: Your Script Serves Clients
If the app developer asks you to modify something in the API or add specific flags please do it and don’t waste time on asking him why or teaching him how to do his job. Unless what he’s asking is a total nonsense then please just do it.
One of the worst things to do is to tell the app developer how to implement something in order for the app to be compatible with your API. Don’t tell me to just use an AsyncTask for this request or that, I’m not even using AsyncTasks (directly at least) to fire API requests. I have my own structure, I use well known libraries and it’s not a solution to build a networking solution just for that case that can be easily fixed from your side.
Keep Your Nulls to Yourself
Back to JSON responses, if an object is null then don’t send it at all! especially strings. Without the app developer implementing a workaround then the string will be parsed as a “null” literal, so just don’t send it.
Unneeded Null
{
"status":200,
"user":{
"id":1,
"name":"John",
"codename":null
}
}
Null values omitted
{
"status":200,
"user":{
"id":1,
"name":"John"
}
}
Data Types
In case you never worked with Java before then you should probably know that it has types and the three example if statements below will not compile
if (user) ... if (1) .... if (str) ...
I was once expected to accept both responses below:
Array of photos is returned, could be empty which is totally OK
{
"status":200,
"photos": [...]
}
No photos available on server so I received false instead!!
{
"status":200,
"photos": false
}
The first response is totally fine, I expect an array and a JSON array is returned. The second one however returns false instead of an empty array (I have no idea why).
As for boolean values, keep it either true or false, don’t use zeros and ones as they need special processing to be converted to booleans since we can’t use if statements with types other than booleans
We also prefer supplying true/false as request parameters instead of 1 or 0.
Stop Spitting DB Rows
Spitting your query result into a JSON object will include many un-needed values and sometimes values that shouldn’t be accessible to the client. We might accept the weird names you chose for your table columns but unneeded fields are still unneeded.
Do some processing and return a well formatted response instead. Make it developer friendly.
Return Useful Responses
Let’s say there’s an API to edit the user’s profile, the following response to such API call is almost useless
{
"status":200,
"message": Profile updated".
}
}
Apps usually store a cached version of profiles and whenever an edit is made the app needs to get the most recent version to store it locally.
Another example of useless responses is not returning the FULL created object when calling an API that creates stuff like bookings, comments or any other thing that the app will most likely need to display after the request is complete.
If I post a comment or send a chat message then you better send it back to me with all the fields included.
Returning Flags
Let’s say you’re making a social network app and each user can be either private or public and your social network enables users to follow each other.
When you return the user object to your application please don’t fuse flags together into one string like this
{
"status":200,
"data":{
"id":1,
"name":"John",
"profile_type":"public_followed"
}
}
Instead do this:
{
"status":200,
"data":{
"id":1,
"name":"John",
"privacy":"public",
"follow_status":"followed"
}
}
For me to get something useful from the first response I’ll have to process like four strings:
public_followed, public_not_followed, private_followed and private_not_followed.
Authentication
If the software solution involves user registration and login then you’ll need something to be sent by the client app with each request to know the sender’s identity and return the data accessible to that user.
I’ve seen some people implementing this by expecting the client (app) to send the user id with each request. What they are doing here is very wrong as they’re fully trusting the client to only send the right id and not try sending an id for a different user. So just get the id of the user and you have full access to his data! And the requests doesn’t have to come from the app itself. It can be from any API client. Don’t ask to get hacked.
Consider generating an access token (look it up if you’ve never heard of it) for each user login. The client needs to send this user specific access token with all requests.
Implementing Facebook Login/Registration
So this is related to the previous point. If you want to link each user to a Facebook account then the client app should do the Facebook authentication and get an access token (Ahha!) then send this token to your server. Your server can then query Facebook Graph Api to make sure that this Facebook token is valid and get the user data.
I saw a case where the Facebook user registration API expects a Facebook user id and not a Facebook token. In this case I can get the Facebook id of any user and login using that id to access his information.
To summarize this Facebook login process:
- Client application does the Facebook login (Your server isn’t involved yet)
- Client application gets the Facebook access token
- Client application send this token to your server
- Your server will contact Facebook servers to check the validity of the provided Facebook token. You can request user profile for example.
- If token is valid then Facebook returns the user details including id, name and other fields depending on permissions.
- You save the user information in your database along with the Facebook id you received from the previous step
- You generate an access token for your own APIs and return it to the client application
- The client application can now use this token you created to make authenticated requests.
Using Postman
Postman is one of many good API clients that can build and test API requests.
Use it while you’re building your APIs, it can save collections of APIs with their parameters. This can become a good reference for you and the app developer and it can also serve as an API documentation with instant requests tests.
APIs URL Patterns
I would appreciate it if your APIs didn’t look like this:
GET http://domain.com/getMyProfile.php // Get my profile POST http://domain.com/updateMyProfile.php // Update my profile GET http://domain.com/getUserProfile.php?id=1 // Get other user's profile GET http://domain.com/getUserFollowers.php?id=1 // Get user followers POST http://domain.com/followUser.php?id=1 // Follow a specific user POST http://domain.com/unFollowUser.php?id=1 // Unfollow a specific user GET http://domain.com/getArticles.php // Get all articles GET http://domain.com/getArticleDetails.php?id=1 // Get article details POST http://domain.com/postArticle.php // Add new article
I would prefer working with something like this:
GET http://domain.com/api/v1.0/users/profile // Get my profile POST http://domain.com/api/v1.0/users/profile // Update my profile GET http://domain.com/api/v1.0/users/id/profile // Get other user's profile GET http://domain.com/api/v1.0/users/id/followers // Get user followers POST http://domain.com/api/v1.0/users/id/follow // Follow a specific user POST http://domain.com/api/v1.0/users/id/unfollow // Unfollow a specific user GET http://domain.com/api/v1.0/articles // Get all articles GET http://domain.com/api/v1.0/articles/id // Get article details POST http://domain.com/api/v1.0/articles // Add new article
The point here is to make URLs more organized and group-able. Removing the ugly .php would be appreciated of course.
Final Words
You might disagree with the above. Fellow app developers might also disagree with me on some points. But as I stated at the top: the post might contain some personal preferences and I might also be wrong about some points. If so then please let me know in the comments.
And I hope this helps to close the misunderstanding between backenders and app developers.
Thanks for reading.
Ghoscher's Blog 