Hacker News new | past | comments | ask | show | jobs | submit login

It's beneficial to approach learning about an API top-down and bottoms-up. The context in which the API operates and then the working of the API in itself. Imagine if you were in charge of maintaining a hardware tool. I first want to know how this tool is used by various customers before learning how the tool works.

1. Begin by learning all the end-to-end product flows this API is going to be invoked within. This is the context in which your API is operating in. It also sets the stage for non-functional requirements such as latency, and availability requirements. How will end customer and business be impacted if this API were to misbehave?

2. Next speak to all the customers of this API. How do they produce the data for your API's inputs and how do they consume your API's output. You will be surprised by all sorts of creative ways in which an API gets used, not necessarily what the API was intended to begin with. But you need to support all those clients so better get to know their use cases. Also, understand how they handle your API failures. The consumers tend to make unstated assumptions about input/output validations and invariants. It's not documented anywhere but floats around as tribal knowledge. Extract that knowledge and document it somewhere. Make sure you are very clear about every single input parameter, how it's produced and its expected values as well as every single output parameter and how it's consumed. Don't forget about exceptions. Often times customers treat exceptions as just one of the expected output parameters and so actually depend on the API throwing that exception.

3. Finally, take a look at the API's implementation. Don't get frustrated if you don't understand more than 50% of the code. It's perfectly fine. Make notes of the parts that make sense and also note down those questions. Ask around. Often some parts makes absolutely no sense to you. But it is there for a reason, someone as competent as you put it in the first place. Again, ask around both within your team and the API's clients. Pay attention to the API's downstream dependencies and how their failures are handled and bubbled up to your clients. Your API's SLA depends on your downstream APIs, learn about them and ensure that it matches the expectations.

4. You also have indirect consumers of your API who depend on the side effects produced by it. Make sure you learn about them. If this API causes a side effect (such as DB update, publish a message to Kafka) then learn how those side effects are consumed. Does someone depend on it? If yes, how?

Though I've described these steps in sequence I find it useful to approach all of them in parallel and over multiple iterations. At first everything is blurry and after first pass you penetrate through about 10% of cloud cover. After 4th or 5th pass you will have a reasonable understanding (~85%) to make small bug fixes.




Sincere thanks for your response. This is probably one of my biggest weaknesses as an engineer so I really appreciate your help.

Right off the bat, I think you hit the nail on the head whereas I have only slowly started to think about how API's are used, rather than just how they're written.

1 is a great point. I'll take some time to get more info on the end to end flows, and I think that will provide some great foundational understanding before even going in.

2. Is a whole knowledge bomb in itself. I hadn't even thought of many of these points. Talking to the consumers is another great idea and I'll make sure to do that.

3. I appreciate the reassurance. Part of why I never built up the skill so far is because it's, frankly, intimidating to start poking at some big system from scratch. Thinking about downstream APIs is a smart angle.

4. I like this point a lot. Seems like a way to level up and start thinking about the bigger picture.

I can already see the benefit of these strategies and how they'll help me develop my understanding. Now I feel equipped to tackle our team API's, not as daunted as I was feeling before. Thanks!


You are most welcome! I'm glad you found it useful.

As you go through this exercise I'm sure you will gain new insights into the process and the API itself. Please document them for the benefit of others around you. The way I see it, you are anyway putting all the effort to learn the system, you might as well put in a little bit more effort to document and get your peer's appreciation in return. Also, you will have something concrete to show for all the time and effort you put in over 2-3 weeks, as opposed to just saying "Right I'm now ready to maintain/change this API".

Written communication and specifically documentation is a very under-appreciated skill among software engineers. But it's a great way to make yourself visible among your peers and spread the knowledge of the system.

The software you write will have impact on customers, but they are far removed from you. The documentation you write on the other hand is beneficial to your peers with whom you work and interact every day so this is a good way to be in their good books. They will appreciate and respect you for going the extra distance to spread the knowledge.

Good luck!


Absolutely. I've always been a huge fan of documentation and push for it when I'm at an org that doesn't care much for it. Thankfully my current org, at least my current team for sure, is very pro-documentation, so I'm more than happy to create documentation for everything I learn and give back to our internal community since I've also benefited a lot from others' documentation.

I also like your point on visibility a lot. That's something I've only really starting learning about recently at my current org, and you make great points there.

Thanks again!




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: