An Open Letter to (mobile) Server Devs

On basically every project I’ve ever worked on that involves a server, I seem to notice the same things that happen over and over and could be preventable with proper planning.  When mobile devs discover server bugs, it often blocks our work and halts development (not to mention the costs associated with that, which are NOT trivial).

So I thought I’d just list the things that I wish server developers would think about when they start building a system, and rant a bit about the mentality we’d hope for in any server dev.

 

Design for the failure case, not the ideal case.

Servers fail all the time.  You should consider what will first go wrong before you focus on what will go right.  If you set up your architecture correctly at the beginning, this becomes easier.  Yes, your project has more boilerplate at the beginning, and you can’t just dive into the things that make programming fun, but remember you are a server; you serve others.  The quality of your work is measured by how close to perfect your work is.  Nobody knows when things are working correctly, but they DO know when they’re not.  It’s a tough life as a server dev because you get very little love.  But you chose that, so what should I say?

Consider at the very start how you’re going to deliver errors to the clients.

 

Think of responses like a textual representation of an object.

I come from Object-Oriented Programming.  Think of responses as objects, and you need an application-wide “baseclass”.

{
    "data" : {
        /* YOUR ACTUAL RESPONSE PAYLOAD HERE */
    },
    "errors" : [
        {
            "code" : 401,
            "domain" : "HTTP",
            "description" : "Unauthorized",
            "recovery_suggestion" : "Your access token may have expired.  Try logging in again."
        },
        {
            "code" : 1001,
            "domain" : "Our Server Form Validation",
            "description" : "Email address invalid",
            "recovery_suggestion" : "Make sure your email is formatted correctly."
        }
    ],
    "message" : "Any arbitary message that is relevant to the response itself.  This response isn't supposed to make sense for any specific context.  They're example fields.",
    "response_time_in_ms" : 1234,
    "status_code" : 200
}

 

It’s not 1982

Mobile Clients prefer textual representations in the response.  Your responses can be verbose and at times redundant.  If you have to echo the http response status code in the payload, why not?  All the pertinent information is in the same place.  To an extent, of course.  It just makes your API that much more easy to work with.

 

The Importance of a Documented API

Your server may be down.  When your server is down, your mobile developer is often stuck when he doesn’t need to be.  Most of the time, mobile devs need any data, so long as it can be used to populate the contents of the UI.  The Server API is a contract.  It specifies what the server team will deliver, and what the mobile developer can expect.  It ensures that two mostly separate teams can work happily in parallel.

If you provide a documented API before it’s even implemented, the mobile dev can get his job done.

It just needs to be simple.  Send these parameters with this method to this endpoint, and you can expect a response of:  (most verbose response here that shows all possible fields that might be defined.  Mark in comments beside that value if NULL can be expected.)

Then you highlight the error scenarios.  Possible error codes and why.

 

Interactive API via Postman

Postman is a very valuable tool.  It’s generally how you resolve disputes with the server devs to the effect of “Server’s broken!  No it’s not!”  You can make your requests outside of the app and inspect how the server is working.  It also makes your bug reports more believable to a server dev, where he can’t really say “stupid user error”.  It’s of course up to the server dev to keep environment variables up-to-date and provide some documentation on how to use Postman in the way the server dev expects you to.

 

This is sort of a working draft, but on almost every project, I wish there would be devs that understand how their work makes its way into the end product.  And if you ensure that your role is one of service, and your customers are mobile developers, keeping a service-oriented mentality, like the Maître d’Hotel, where you derive your happiness when your customers are happy, this surely is the way for you to become a rockstar.