You write the server, I write the client: Best practices for designing an API?

Question

I'm working on a brand new application that involves a client and a server. Specifically, it's a native mobile app talking to a web server, using a custom API that we will define. I was hired to write the client and another guy (I've never met) has been hired to write the server.

To get started we need to agree on an API. We both have very different perspectives on it, working with different technologies. Each of us might not even be sure what sort of small changes make things easier or harder for the other guy. I can't deliver a client if his server isn't working, and his server is pretty useless without a client.

What are good strategies for dealing with arrangements like this? I know the answer usually boils down to "it depends on your situation" but if I can learn from anybody else's mistakes, I'd sure like to avoid making them again on my own.

Answer 1

What I do is start writing the client, with no server, my repository class just returns fake responses, but with data that makes the UI work.

That gives me a basic understanding of what I need the API to do.

As you go, for each feature, start with this. Give the interface to the server guy and you keep working with your mockup while he creates the real implementation. When he's done, you see if it works.

You'll never come up with a perfect interface by writing it all down first, there will be a lot of back and forth. You asking for changes that make the UI easier. And him asking for changes that make the server side programming easier. It's about compromise. In the end the UI/Client generally wins since it's all about the simplify the consumer. You'll likely only ever have one backend, but probably will have many clients written in different technologies calling it, so making the client life easier is generally better.

In the end, though, both systems should work independently. Your client should work on your mocked repository, this allows you to test the UI without a backend running.

His server, should have a bunch of tests that mimic calling it like your client would.

In the end you have to systems that only talk through a common API, and both can be demonstrated and tested without the other existing.

Answer 2

There are lots of mistakes to make. Most of which can be recovered from with enough blood, sweat, cash, tears or vodka. The one that you can't recover from is that you need to remember to bake in API versioning from the get go. Opens the door to fixing v1 issues without tossing out v1 clients.

One feature I love to see API devlopers give is some sort of sandbox/canned data/test mode I can use. Opens the door to lots of automated testing scenarios one just can't get with live-only data. Not sure if this is even possible for your API, but it could be nice.

Answer 3

Create an ICD (Interface Control Document)

It's important to nail down exactly what data format you'll be using to pass data between your applications. Nothing excessive, just a simple drawing and some brief explanations.

That means, if you're using a similar format (JSON/XML), describe what a basic schema would look like and how those items are determined/used.

After that is sufficiently nailed down, you can both work toward making your ends meet in the middle.

You could have the most awe-inspiring UI with the most scalable data store ever, but when connected together both speak gibberish.

Think of the API as if it were a Domain Language

For instance. In the world, there are hundreds of 'Natural' languages but many international industries are based on one, and only one language.

For instance, Programming (or technical industries in general) use English, music uses Italian, Science uses Latin, etc...

English was chosen for tech because of the already extensive (and quickly growing) vocabulary of words to explain technical issues. Italian for music because of tradition. Latin for Science... who knows.

The point is, everybody (or, at least the majority) agree on the standard and follow it even if it inconveniences them personally.

---

By nailing down the communication, both developers can work toward meeting in the middle without having to waste time (and performance) by transforming the data into intermediate formats.

Ideally, it's best to use a language that both the server and client understand. Like, transferring JSON between a Node.js server and Javascript being run in a web browser.

It doesn't really matter who chooses the format as long as both sides can agree/compromise.

Answer 4

Honestly, it doesn't depend on the situation at all. The API should always be written to make it easier for the client to use.

That means error codes as well as messages so that, if he changes the message later, it doesn't break any of your code. It means returning the same key fields that you sent to him. It means asking for the least data that identifies the information you're trying to give him, and returning at least as much information that you need. It means not relying on your caching his data (except the minimum) from action to action.

We are writing an API for external clients and we are assigning development time to writing a useless client app, just so that we can quantify how easy it is to write against our API.

Making the client code better is always the settling factor in any disputes like this, except where it absolutely, technically cannot be done.

Answer 5

The biggest thing in my opinion is constant communication, especially early on. Start with spiking some functionality pretty much in lockstep with each other to get the basic calling style (RPC vs. RESTful) stuff and message format nailed down, and go from there. Make sure you have multiple environments so you can keep working against both a reasonably stable (i.e., nightly) build as well as the newest stuff the server-side developer is testing.

Most of this should be driven from the UI. Tell the server-side developer what data you need and have a conversation about how you can retrieve it.