Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
Here's a similar question that follows the same lines. programmers.stackexchange.com/questions/36116/… –  Evan Plaice Oct 13 '11 at 22:22
add comment

5 Answers

up vote 16 down vote accepted

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.

share|improve this answer
1  
+1 I really like this approach. A co-worker and I, while in an undergrad class, used this method. He worked on the front-end and I worked on database implementation. His fake interface made my job a lot easier too. –  David Peterman Oct 13 '11 at 20:48
    
I'm using the approach right now at work...works great. The most important thing is that you NEED to communicate while doing this. –  CaffGeek Oct 13 '11 at 21:15
1  
Specializing the back end to the requirements of the front end you happened to develop first makes the work for every other front end harder (unless you're going to customize the back end for each front end). –  David Schwartz Oct 14 '11 at 0:43
    
+1 Agree on the back and forth.. come up with a general idea and go with it, but don't skip the design phase knowing this fact. You should still try to hash things out ahead of time though people hate doing it. –  staticx Oct 14 '11 at 1:52
    
@David Schwartz, you don't customize the backend by making trade offs to good design. However, you need to write the backend in a way that front ends will want to use it. Not in a way that makes writing the backend easier. –  CaffGeek Oct 14 '11 at 13:27
show 1 more comment

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.

share|improve this answer
    
I disagree with the "Typically, the person writing the server should provide this info" comment. as the needs to the user outweigh how the data is stored. Frankly, the UI doesn't care. And shouldn't. It sends data in logical units. How that gets saved, doesn't matter. If I want a contact record, I don't care if it means the server goes to a db, flat file, ldap, or a combination or something else. The API should be easy to use for the client. You'll typically write far more clients than servers, so the server has to take the pain, so to speak in order to simplify life for the client. –  CaffGeek Oct 13 '11 at 21:19
    
@Chad Thanks for the feedback. I modified my answer to remove the bias and emphasize the point I was really trying to make. –  Evan Plaice Oct 13 '11 at 22:21
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.