
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&#x2F;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.

