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.

Is it feasible that we have a layer of API simply for the reason so that people in the team don't have to understand the actual implementation of the individual components each of us are working on?

I had this thought because I started to find that some times when working a project with a team of people (I am new to working in a group), it is kind of difficult to know where to start from.

We want to split a huge application into parts so that each of us can concentrate on our own part while at the end of the day, we still want these parts to all work together without having every member to know thoroughly about the actual implementation of every parts.

But an API to me, usually serves as an interface for "external" developers to extend on or build new things from our work without having to go directly into the core part. Since we all working in a team, having an API for each components just for us to work among ourselves seems a little overkill and funny.

So what is the usual practise when it comes to situations like this? Although I am using Java in my case, I think a correct practise for such situations work for projects of all languages, right?

share|improve this question

migrated from stackoverflow.com May 25 '11 at 18:30

This question came from our site for professional and enthusiast programmers.

5 Answers 5

up vote 5 down vote accepted

Think of it this way: When a brand-spanking-new developer joins the team, you're going to assign him to a given area of the project. Wouldn't you like him to be able to get up to speed on that section of the project so he can complete his assignment, or do you want him to spend three months learning the whole massive edifice?

Or from your side - suppose you spend a lot of time on another project and need to fix a bug, wouldn't you like to be able to limit the scope of your debugging efforts?

(There is a method here, just hang on.)

API stands for Application Programming Interface. Nothing in that name defines at what scope it is defined for. In my opinion, every class has an API. By always thinking about how the class would be used from elsewhere, you can make each class, package, web service, and so on easy to use and maintain.

As you plot your design at first, you will see several large sections. For example, in a shopping application, you can break it down into Inventory, Billing, and Shipping. Each of those will have specific things they need to communicate with each other. Each of those in turn can be broken down further. You end up with a tree. The easiest to maintain applications do not communicate across branches in this tree in undefined ways, like using public fields, public statics and singletons. They only have to worry about the fields and objects they own, through those object's public interface: its API.

Everything has an API. What you should be worrying about is whether or not that API is easy to use, maintainable, and testable, not whether you need one. A well-defined interface helps you limit the scope of feature additions, bug squashing, and everyone's learning curve.

share|improve this answer
    
If every class has an "API" the term isn't very useful. –  Jeremy May 25 '11 at 19:20
    
I think the term is perfectly scalable. 'Public Interface' is practically a synonym, and that applies at every level as well. –  Michael K May 25 '11 at 19:24
1  
Look at it this way: an API is an interface, how you implement you API depends on your needs. A version-controlled XML API will be overkill for services that will only be used in house. On the other hand, a Java API is perfectly reasonable for in-house work. Both are APIs, with highly differing scope. –  Reverend Gonzo May 25 '11 at 20:32

I think you should always strive to define an API as early as possible. For these reasons:

  1. It really helps to nail down requirements.
  2. Helps define in concrete terms what each team member is expected to do.
  3. Helps manage scope - when all requirements have been met then your API(s) are complete.
  4. You can more easily swap out different implementations. This helps if you are testing or just trying out new ways of doing things. You still have to meet the same requirements but can do so in different ways and then decide what is best - time permitting.

There are probably other good reasons but these are the main reasons I do it that way.

share|improve this answer

I think it would be overloading "API" to say you need to do that here, but certainly focusing on the public interfaces that will integrate and co-maintaining test cases are very helpful things to do up front. This way we literally have a conversation that goes like this "these are the methods I expect your classes to provide, and here are some specs they would need to pass in order to provide the functionality I'm expecting".

share|improve this answer
    
But I still don't quite understand. So it is a normal practise to create APIs for internal development on a project? It may be good that I can simply expect what other team members would provide in their classes and just concentrate on my own, but wouldn't it be easier if I don't even have this layer of API and then ask the team mate to directly make use of, say the getters and setters, in my actual classes? Then this way, we don't have to spend time creating another layer of API, which could provide methods that the actual implementation already has. Furthermore, it's just among the team? –  xenon May 25 '11 at 18:52
    
Right I would not create additional classes just for that purpose the way you might with a commercial API. Principals of information hiding and encapsulation do not change. Still, defining the parts of the interface that are important to integration between developers are helpful things to do up-front. –  Jeremy May 25 '11 at 19:18

It's only an "API" if you call it that. I'm not sure if you're carrying any negative connotations with that, but contracts between logical code modules are a good thing, even if you're the sole developer. And the contracts are only as rigid or flexible as you and your team need them to be.

share|improve this answer

Good overall architecture that is maintained somewhere in a wiki/Modules owned by individual or two (virtual teams)/well defined interfaces / integration tests around these modules and source control.

share|improve this answer

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.