Ask HN: What are the biggest API development issues that you face?

[harshulj]

Some issues that I face are : 1. Deciding on a common API structure amongst teams. 2. Keeping up to date with the changing API structures. 3. Suggesting modifications to an existing API. 4. Waiting for backend developers to finish APIs before getting started. 5. Notifying co-workers of deprecations/breaking changes. If yes then How do you tackle these issues in your current work?

[carbide]

A common API structure amongst teams? It's hard enough coming up with a good API abstraction WITHOUT a team! I do my best to keep things as abstract as possible and leaving myself in a place where I can pass along versioning data with different object information so I don't massively break things.

Some of the biggest issues I face still include lack of foresight, thankfully I haven't had to have any truly major redesigns in any of my projects but there are always things you don't expect.

Working in the private sector FOR someone the challenges are more along the lines of "Can the other team really define what they want?" I can't define a good well abstracted API when they're unexperienced or just don't know what to ask for or even what they want.. but that problem tends to extend beyond programming :)

Other big problem: Documentation. I tend to be a 1 man team that interfaces with other teams of multiple people. I don't usually document well. That sometimes bites me in the ass months later, but that's a typical story -- document and comment! Know WHY you chose to implement an API the way you did. Was it your choice? Was it the other guy? Did you miscalculate something or not realize how a project might expand? Documentation goes beyond defining the API/ABI and again something I'm pretty bad at.

[dhruv_parmar]

I feel most of the times API structures are decided in meetings on whiteboards and it becomes a pain maintaining context across such meetings. Also with remote teams the same process is usually done over email.

Also propagating deprecations/breaking changes to the entire system is also a big pain point.

[harshulj]

How do you tackle such problems?

[conorgil145]

Keeping the API documentation updated is a major pain point IMO. Many developers do not update it at all and often times it does not get updated when something is deprecated or removed from the API

[mohammadshabaz]

Documenting the API contracts and keeping it updated is a major pain-point. Mocking the api until the real API is ready also takes up time.

[blater]

Are you doing model driven development for the contract - building the contract artifacts first (e.g. the wsdl/wadl/whatever) and generating documentation and some of the code off them? If you can then the documentation problem goes away. You just regenerate the docs from the contract as part of the build.

Mocking takes time but means other teams can develop against your API before you've written any code, so while your coding effort is a little more, the elapsed development time across all teams is shorter. That can be a big win.