Magic fields in the API

On a recent project I was working on, I was helping to build a frontend application. All the data that we used was managed by a partner, backend team that exposed the data through some APIs. That's a fairly standard setup. The weird thing was that in most cases, the APIs provided direct access to the datastore. They didn't do much validation, they just provided a way to get and set the data. In some cases, if particular fields were set, then some magic would happen.

In one particular case, our frontend would allow users to update their profile information. To do that, we would ask the backend for the profile, display it to the user, let them make the changes they wanted, and then we'd send the updated information to be saved by the backend. However, one of these magic fields exists in the profile, and it caused some problems. The magic behind this field worked in such a way that if we saved the exact profile information that we retrieved, then the profile would be broken.

Let's look at that again. If I call the API to retrieve the profile information, then call the save API and give it the exact information I was just provided, it would break the profile. Really? Yep. The expectation was that there was a field that needed to be cleared out before sending the information back to be saved. If it wasn't cleared, then the profile would be broken. Of course, this wasn't documented anywhere, it was just expected that everyone would know this.

Something doesn't sit right about this design. It would make sense that if this field had to be cleared out, then it would either be cleared out by the retrieve API or the save API would give an error if it was present.