A Short REST
I'm starting to wonder if we need a "Representative API" category. There are just so many ways in which a developer can mess up basic tasks, like mapping a RESTful API to their backend.
Today's anonymous submitter was working with a REST API provided by a "world leading parcel" company. Everything started well. The documentation was thorough, contained links to example projects, and it came with a Swagger API doc. Based on that documentation and based on the Swagger doc, they went ahead and tried to CURL the API for a specific endpoint:
curl -X POST https://[redacted]/rest/returns
It returned a 500 error, with no description of the error which occurred.
They tried playing around with the body content that gets sent. They went back to the documentation, and discovered an inconsistency- in the docs, it suggested that the url should be rest/v1/returns, so they tried that. That didn't work. Another section of the docs disagreed, and suggested a slightly different URL pattern. That also didn't work. They tried using Swagger's code generation functionality to build a client right from that doc, and tried again. That also didn't work.
After many hours of staring at information-free HTTP 500 errors, our anonymous submitter went ahead and tried running one of the sample projects. It worked.
It was a short program, so it wasn't exactly hard to trace through it, line by line, and see if there were any obvious differences. There weren't. Our submitter's attempts send the same request to https://[redacted]/rest/returns failed, but when the test program sent its requests to https://[redacted]/rest/returns/ everything worked just fine.
A pair of shell commands proved it quite easily:
curl -X POST https://[redacted]/rest/returns # 500 errorcurl -X POST https://[redacted]/rest/returns/ # 201 result
And that's when they spotted it. The trailing slash. The service was configured so that returns and returns/ were actually separate routes. returns wasn't a valid route, so cue the 500 error. Every single piece of documentation ignored that, and the only place where the URL was accurate was in the test application. Which, at least there was a working test application.
Our submitter adds: "God, I hate web development."
[Advertisement] Utilize BuildMaster to release your software with confidence, at the pace your business demands. Download today!