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.
So lets talk about the responses we have to send to this API. It’s a JSON body with a dynamically constructed object with properties representing the fields of the form. And although the field property has a name of UniqueID, it has to be returned in a fully-qualified manner, prepending each containing group’s UniqueID. So if a group name changes, all fields under it change in the response. It could have been easier to just send the UniqueID (since it is supposed to be unique, right?). And the structure of the object, what the fuck. Why not just have a simple array of key/value pairs. Instead, you have some mystery object where a property may or may not exist. It’s the same shit, iterate over properties or iterate over an array. One can be handled in code with a class and a generic List, the other has to be done through a complex library like Newtonsoft and still results in an object that can’t really be navigated. I get that JavaScript is taking over the goddamn world, but JS makes everything harder for no real benefit.
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.
