I am not an expert in API (Application Programming Interface) design. Full disclosure, I've never even built a publicly consumable API. I have built internal APIs that try to follow patterns that I've observed in the wild; but, my experience is certainly limited. That said, I do have some strong feelings about API design. Specifically, I am dubious of any API that allows for the generic "partial updating" of existing data. I believe that such API design lacks meaningful semantics and allows both creators and consumers of the API to think too much about "data persistence" and not enough about domain modeling.
That said, let me be clear about my reservations. Given an API that already has data for a Person X:
- id: 4
- name: Person X
- age: 22
- createdAt: 2016-04-04
- updatedAt: 2016-08-01
... I try to avoid building an API that allows me to send generic UPDATE requests to change arbitrary field values:
UPDATE "Person X", Set "name" to "Person Xtraordinary"
To me, this kind of update lacks meaning. It lacks sematics. When you have a conversation about this kind of update, you have to include all of the data related to the update in order to ensure that all parties are on the same page about what exactly is being discussed. To me, this would be like talking about design patterns without giving design patterns names.
This kind of update also feels very ambiguous in terms of what is valid. Meaning, can I update the Person's "name" and "id" at the same time? Is it even legal to update the "id"? Do I have to provide the "updatedAt" field? Or, will that automatically update with the current timestamp? Can I set the "createdAt" date to be after the "updatedAt" date? Can I add a completely new field like "favoriteColor" when I send an update?
None of this is clear because UPDATE is not intentful. It doesn't really convey a specific desire on behalf of the consumer. I believe that requests of this nature should be wrapped up in meaningful "actions." Instead of "changing the name field", you're "renaming":
RENAME "Person X" to be "Person Xtraordinary"
Now, we can have a clear converstation - I'm talking about the "rename" action, not the "update action that happens to include a 'name' property and no other properties at the same time." It also becomes much more clear as to what data is valid. For example, in a "rename" action, it wouldn't make sense to also include the "age" field. Actions also help articulate the surface area of the API. They demarcate the set of meaningful requests that a consumer can make.
NOTE: I understand that documentation removes all ambiguity. But, I am talking about this from a mental model viewpoint, not from a "Read the manual" viewpoint.
Of course, not every request to an API can be wrapped up in a more semantic action. I'm not crazy! Sometimes, "update" is really the most meaningful thing you can do. But, I would suggest that this is perhaps rarer than you would think.
Viewing the API in terms of "actions" also helps prevent both the consumer and the provider from thinking too much in terms of data persistence. Admittedly, I have a lot of trouble articulating why I think this is a good thing, but my gut says it is.
I'm sure I haven't laid out the best argument. My reaction to "UPDATE" is definitely one rooted in "feelings" so it's hard to layout in a logic way. Perhaps the only thing I've truly convinced you of is my own buffoonery. At the end of the day, however, I believe that API application state is often changed through semantic actions; and, those actions can be clearly reflected in the API landscape.