Hey everyone! I've been discussing with some colleagues whether it's worth documenting error responses like 4xx and 5xx statuses in our APIs when they don't provide any extra meaningful information. After looking into the OpenAPI specs, I understand it suggests that we should document expected errors, but I'm struggling to see the value in documenting common statuses like 404 or 401, where the meanings are pretty clear, such as 'resource not found' or 'unauthorized'. I noticed that in some APIs, these responses are documented as just a reiteration of the code's meaning without additional context. What do you all think? Is it beneficial to document these, or should we focus on more informative error messages? Cheers!
6 Answers
While it's true that some HTTP codes are obvious, documenting them creates a contract for how your API behaves. If clients know exactly what to expect in their responses, it streamlines their development process. Plus, it can help reduce support requests!
Totally agree! The key is in how your API handles these errors. If a simple '404 Resource not found' isn’t helpful, then expand on it! For instance, '404 returned when the project ID doesn't exist or the user lacks access' gives more insight. It’s all about what your API delivers versus standard meanings.
You should document all errors your code could throw, especially ones unique to your application. This way, API consumers know exactly what to expect. I find it useful to include a brief explanation for common codes like 401 and 403, as they can mean different things based on the context of your API.
Absolutely! It saves developers from unnecessary confusion.
Right! And don’t forget the value of consistency in documentation. If your API documentation is uniform and thorough, developers will appreciate it, even for basic errors. Sometimes the simplest errors actually have more complexity beneath them that deserves to be noted.
Thanks for all the diverse insights! I feel like I have a much clearer understanding now!
I get where you’re coming from! The thing is, while basic errors like 404 are well understood, there might be specific cases worth calling out. For example, if a 404 is returned because a user tried to access a path that doesn't exist, it could be helpful to clarify that. It adds some context that could help users debug faster, you know?
Thanks for your input! That makes a lot of sense. It's about setting clear expectations.