API docs will tell you how to use an API. But when things go wrong, you can be left on your own. Error messages are often incomplete, misleading, or unhelpful. And what are you supposed to do with NoMethodError: undefined method '[]' for nil:NilClass, anyway?
When you learn an API, framework, or library, you can’t just learn how to use it when things go well. You also need to figure out what to do when it hands an error back.
How do you break code?
There’s an easy way to learn what to do when an API you’re using breaks. Break it yourself!
For example, I’ll:
-
Pass data of the wrong type. You could pass a symbol instead of a String, a String instead of an Array, a Hash instead of an Array, things like that.
-
Pass incomplete data. You can pass
nil, hashes without some fields filled out, and objects that have just been initialized. -
If the API requires network access, disconnect from WiFi or pull the network cable. Does it just time out, or does it tell you which service it couldn’t reach?
-
If the API allows you to pass in a block, throw exceptions inside the block, or return data of the wrong type.
A great API will tell you what you did wrong. An excellent API will tell you how to fix it. But most often, you’ll run into a Ruby NoMethodError, unexpected nils, or, worse, getting totally bizarre return values back.
Why break code?
This isn’t all bad. If you’re playing with an open-source gem, you can take time to understand where that unexpected behavior came from and why it happened. You can debug and read a little bit of code to learn a lot about how the library or API works.
Once you discover where the NoMethodError is coming from, you can go a step further. You can fix the error message for the next person to run into this problem for real! Little error message fixes make great open-source contributions and easy pull requests. And they make the entire Ruby ecosystem a little better for everyone else.
Even if it’s a closed-source REST API, you can still get something out of this exercise. After you see the different errors you’ll get from the API, you’ll have an easier time fixing the problem when you run into an error for real.
Once you become more comfortable seeing and fixing errors in the code around you, you’ll see broken code as a puzzle to be solved. You won’t automatically recoil when you see an exception and backtrace dumped to the screen. Instead, you’ll see them as an opportunity to learn more about the system you’re working with.
Finally, you’ll know that when code breaks, you’ll be able to put it back together again. You’ll improve your confidence in trying new libraries and APIs. And that boldness will increase your rate of learning new things.