Is it normal to give up with API documentation and just figure it out oneself?

Title pretty much says it all. I’ve been going through the reddit API mission and have been doing better just looking at the response my get request has been getting (after being converted with .json()) and figuring out the logic for how it’s structured by just looking at it. There is documentation for the reddit API (auto-generated documentation, which seems sketch), but it is just confusing.

Should I nevertheless try to get better at understanding documentation, or is sometimes documentation just unnecessarily confusing? If anyone has any experience from having to work with api’s in the “real world”, like for a job, I’d much appreciate it.

NOTE: I don’t mean here anything like “completely ignore the documentation”, obviously it’s important for seeing what the names of requests are, and setting up authentication. But, for other things, perhaps it’s not always too helpful.

1 Like

API docs (eg. https://swagger.io) usually show not just method names, parameters, return types but also the data model through the response.

One view supporting ignoring docs is “Do whatever you need to get the job done”.
In this case, it doesn’t matter what the docs say if it can’t give you the data you need, and the approach of looking at the dictionary output from r.json() and manipulate from there will be better use of time.

The opposite argument is if you want to do a better job than the bare minimum (“hack your way through to usable outputs”) . In this case documentation could help you understand how the data you are seeing is structured and designed. If you know the range of possible inputs, which could influence the output size limits at a certain depth of nesting of the response, that can influence how you code. If you do leetcode or other short coding challenges, thats like changing your approach based on the max input constraint. Docs may tell you how big size of data you can expect 1 call to return. If you know input date range constraints, that helps you estimate how much data there will be if you queried everything at once. Both influence system design.

For an API in developing stages, It may be the case that the current data available is not what will be available in future (assuming the docs correctly represents what will be available in future), so even if you queried all the data, the patterns and data relationships you see are not all the patterns that can occur in future. Writing code and making judgements based solely on responses you get now may not be good for future-proofing.

By understanding the data model (which could reveal recursive relationships), you can make good judgement on which api to call when there are 2 similar ones, (the one returning a subset, or superset of data), infer how the entities are related (eg. Entity-relationship-diagram) which affects how you flatten and represent the response, or how you can transfer the data from the API reponse into your own custom database model for your own other analysis(Because it may be too big to store as a single dict in memory).

And all these is just from a user point of view. What if you want to speak to developers/maintainers of the API, or even become an API developer one day. It helps communication (feature requests, bug complaints) if you know how the API is designed, and that comes easier from docs than wild inferences from output alone.

To me the value of the docs is to understand what’s possible more than how to do it perfectly. A personal project may allow hacking to results but on the job, there may be standards to adhere to, so how much docs you use depends on the requirements of the job, your familiarity with that api, and familiarity with api concerns in general.

2 Likes

I see. Thank you for your well thought out and detailed response. I really find it useful. I see based on what you said that there are strong advantages to understanding the api. That being said, at least with this particular api, I find myself going in circles, and only capable of understanding the docs after staring at that which is returned from making api calls.

For example, mission 110-5 has in its instructions the following:
" Querying the comments endpoint at /r/{subreddit}/comments/{article} returns a list. The first item in the list contains information about the post, and the second item contains information about the comments."

Looking at https://old.reddit.com/dev/api#GET_comments_{article}, the documentation there says nothing about a list being returned. It’s especially confusing because it’s not like every api call returns a list, up until this point in the mission, reddit api calls always returned a flat-out dictionary.

Logically, if there is nothing about a list being returned within that subsection of the documentation, the only remaining place where I should be able to infer that a list would be returned is in a different part of the documentation. That place would naturally be in some part of the beginning of the documentation that has information about how requests work in general. Maybe there, there would be some information on recursive relationships, as you mentioned. However, as far as my abilities in reading documentation go, even after repeatedly scanning the documentation for an hour, I seem to just not be able to figure it out.

Another approach I took was looking for logical relationships elsewhere, trying to see if maybe what’s going on is just a matter of common sense. The request I made was structured as /subreddit/comments/article. So, I try seeing if perhaps what I must do is see if there is some documentation for /subreddit/comments that generates a response. From there I’d be able to check if /subreddit/comments/article possesses a relationship to it. But this approach was no dice, I could not find anything in the documentation on simply /subreddit/comments, and to double check, even making an API call to, say, r/python/comments, brought up nothing.

It’s very frustrating. I think my main issue is that, while I 100% agree and see your points in understanding the value of figuring out the API documentation – even if it is confusing and tedious to do so, it almost seems impossible to read this documentation and predict what results would be returned. That is, I can only know in what way the data will be returned and what structure it will have after I make an api call. Logically, one of the three must be true to explain why I’m not able to figure this out, either

  1. The API documentation is insufficient
  2. The API documentation is sufficient, but confusing to a point where it would be extremely difficult for most people, especially beginners to understand.
  3. I’m just not seeing something, and need to get better at understanding documentation.

I really hope it’s 3, and that perhaps after working with multiple API’s, I’d get better at picking up new documentation for new api’s. However, at the same time, it’s a little disheartening since because I’m new at api’s, I truly can’t tell if (1) or (2) is the case, all I can do is bang my head against the wall trying to figure something out, without the ability to tell if that which I am trying to figure out (that being, understanding the API without making calls to it, going solely off the documentation) is impossible to do because the documentation is bad.