Writing a value to a simple field is straightforward. Writing to a relational field, which holds connections, is not, and the Command API is how it is done. This piece is about it.
Why relational writes are different
Writing to a simple field, a text field, a number field, is straightforward: the field holds a value, and writing sets that value. A relational field is different, because it does not hold a simple value; it holds connections to records, potentially many of them. Writing to a relational field is not setting one value; it is expressing a change to a set of connections. A developer might want to add a connection, remove one, replace the set, and these are genuinely different kinds of change. Writing to a relational field needs a way to express which kind of change is meant, and the Command API is that way.
What the Command API is
The Command API, in Odoo, is the way a developer expresses, in code, a change to a relational field. Rather than a relational write being an ambiguous setting of a value, the Command API lets the developer express the specific change meant: a command to add a connection, a command to remove one, a command to set the connections to a particular set, and so on. The Command API is, in essence, a set of commands for the genuine kinds of change one can make to a relational field's connections, so a developer's relational write expresses precisely the change intended.
Why this matters
The Command API matters because relational writes are common in Odoo development, records are connected, and a developer working with records frequently needs to change those connections, and they need to be done correctly. The Command API is what makes a relational write express the genuine, specific change the developer means: add this connection, remove that one, replace the set. Without the right command, a relational write might not do what the developer intends, perhaps replacing connections when the developer meant to add, or the reverse. Using the Command API correctly is how a developer ensures a relational write genuinely makes the change intended.
Using the Command API correctly
The practical point for a developer is to use the Command API to express, precisely, the genuine change meant when writing to a relational field. When changing a record's connections, the developer should be clear about what the genuine change is, adding, removing, replacing, and use the command that expresses exactly that. A relational write done with the right command genuinely makes the intended change; a relational write done carelessly, with the wrong command or an unclear expression, may make a different change than intended, with consequences. Relational writes deserve the care of using the Command API to express precisely what is meant.
The takeaway
The Command API in Odoo is the way a developer writes to relational fields, the fields that hold connections to records. A relational write is not setting a simple value; it is a change to a set of connections, and there are genuinely different kinds of change, adding, removing, replacing. The Command API provides commands for those, so a relational write expresses precisely the change intended. Using the Command API correctly, expressing the genuine change meant, is how a developer ensures relational writes do genuinely what is intended. For how we approach Odoo, see our ERP practice.