API Management – How to Prevent Internal API Changes from Breaking Other Projects

I think you are pretty much on the right track... It is hard to say if any particular way of structuring folders as "the best", but I can share what I have seen. In particular, the way ASP.NET MVC structures this sort of thing is as follows:

• Models
• Views
• Controllers
• {Miscellaneous other folders}

Models Contains the classes that represent your view models, or in the case of an API project, the data types that your API sends and receives; eg Person { Name, Rank, SerialNumber }.

Views Contains the files which generate your views; for an API project you don't really have views, you would just use some sort of JSON or XML serialization layer, so you probably don't need something like this.

Controllers Contains the classes that have your actions on them. This is pretty much what you are talking about doing, but it is worth nothing the separation between the data class (ie the Person object, with { Name, Rank, SerialNumber }) and the Person controller, which supports GET, PUT, POST, DELETE of a Person object.

Miscellaneous other folders would contain any other resources you need; also not all that necessary for a purely API project.

If you don't have tracking of changes as requirement on this object (e.g. "User John changed name and birth date"), simplest would be to override whole object in DB with one you receive from consumer. This approach would involve slightly more data being send through wire, but you are avoiding read before update.

If you have activity tracking requirement. Your world is much more complicated and you will need to design how to store information about CRUD actions and how to intercept them. That is the world you don't want to dive into if you don't have such requirement.

As per overriding values by separate transactions, I would suggest to do research around optimistic and pessimistic locking. They mitigate this common scenario:

1. Object is read by user1
2. Object is read by user2
3. Object written by user1
4. Object written by user2 and overwritten changes by user1

Each user has different transaction, therefore standard SQL with this. Most common is optimistic locking (also mentioned by @SJuan76 in comment about versions). Your version your record in DB and during write you first take a look into DB if versions match. If versions don't match, you know somebody updated the object in the meantime, and you need to response with error message to consumer about this situation. Yes, you have to show this situation to user.

Notice that you need to read actual record from DB before writing it (for optimistic locking version comparison), so implementing delta logic (write only changed values) may not require additional read query before write.

Putting in delta logic highly depends on contract with consumer, but notice that easiest for consumer is to construct full payload instead of delta also.