So, an API is by definition an application interface, meaning it should be usable by applications. But you know who really has to use them? People. Developers. And if you’re going to write an API, you should make it usable for the interfacing applications, but simple and friendly for the developers. I don’t think I’m going to hear any argument about this.
I’m writing here to bitch and bitch and bitch about a project that is breaking me. I expect it will be the last project I do with this company. This API I have been tasked to consume and integrate with our own system is so difficult to work with and so brittle it is mind-numbing.
When you read their documentation, which is perpetually out of date, and see the data you are working with, the initial conclusion you get is that you literally have to write a UI as defined by their specs. And that would be the easiest solution, but the dumbest one because then they should just write it themselves and host it for everyone instead of making an API.
The project involves forms. We fill them out and send them the results. However, we already have our own forms, so the integration should be as easy as taking our values and translating them to their values. As part of the integration, they will send us a JSON file with a form definition. This JSON file contains EVERYTHING needed to construct a UI. It has the field names, the form control types, the validations, groups (with potentially infinite nesting), rules on groups, required attachments per field, permissions… you get the point here. It’s not just a simple form definition.
Ok, so I parse out the groups and fields, then add mappings and translation code. The translation code is off the rails because a “No” in our form must be converted to a “No” in their form. And a “No” in their form is a GUID. A GUID nested under the potential response values for a specific question. So yeah, not just mapping questions, but mapping answers. On a form with 200+ questions.
Then on top of this, they implement versioning. So a form can be updated and we’ll get a new definition. They may (and have done so) rename groups or fields or answers, which just causes the translation code to blow up. Call me a lame programmer all you want, but I’d like to see someone effectively handle a value they’ve never seen before. I’ll take the hit for not wrapping everything in an IF to see if the field was removed or renamed. The timeline demanded does not permit that level of attention.
That’s only part of the troubles. For each form we complete, we have to make multiple service calls. Four, actually. And today, they told me I’m supposed to be making a fifth call, even though things have been working for the 15+ test cases I’ve successfully completed so far. Ok, that little gripe is not really about a specific API, but more about how the company itself has really created a monster in sum.
So back to the meat of the topic, the simplicity of an API. So when you want someone to use your API, you want to make it easy. If you are updating a child record, you shouldn’t have to specify the ID of the parent unless you are allowing that ID to be changed. You can get everything you need from the ID of the child. So why in this API must I provide so much data about so many related pieces when all I should have to provide is the ID of the data I am updating?? And another point: the values I’m returning aren’t updatable values anyway. All that’s happening is the message is being fat and heavy and data is being thrown away. Or maybe, the data is being saved and my work is saving them the effort of looking it up for themselves. If that’s the case, then its unvalidated data and subject to exploit. There is no good answer here.
That’s as much ranting as I want to do right now. Although it feels good to get it out, it doesn’t give me any improved perspective of the project or its viability.