I really enjoy testing APIs, but let’s face reality here: every job has its frustrations. One of the things that I have found frustrating in API testing is when an API is inadequately documented. There is something fun about digging around and figuring out what paths there are in an API and how it works, but some APIs make this too hard.
When I’ve worked with hypermedia APIs, I’ve found they generally include enough information in the calls themselves, that with a little domain knowledge you can figure them out fairly well. But I’ve also tested APIs that don’t have any self documentation and only partial external documentation. I’ve had to go digging through the code base and I’ve had to try and figure out who I could ask about stuff and kept banging my head against the API until I eventually figured out how it worked. Doing this kind of thing can get very frustrating.
As with any code, APIs need to be testable and when they are written without documentation and using magic numbers and other anti-patterns, test-ability drops. We don’t need every detail documented, but there should be enough there that someone new to the API can figure it out fairly quickly.
Photo by Steve Johnson on Unsplash
offbeattesting 
1 Comment