Assume that you have the following 3 entities:
1 Manual has multiple versions and 1 version has multiple Documents.
I want to build a Web API that allows customers to insert their manuals, versions and documents, but what is the best practice?
Do I accept the posted data object in a nested XML/Json structure:
<Manual> <Versions> <Documents/> </Versions> </Manual>
or do I want the customers to add the data entity per entity?
Additionally, how does this work with primary keys and foreign keys between the 2 systems? My database creates a PK per entity and so does my customer's database. Should I store his reference numbers or should he store mine for future updates, deletes and related inserts?
Both, Allow the customer to bulk import/export a nested structure AND give them the ability to add a single new document to a version.
Again, Both. Use a combined key of an Id for the customer which you generate, and the customers PK for the manual/version/document.
This allows advanced customers to use their own key. Which they will prefer. and you can push back an error to them if they send a duplicate, rather than having to accept the duplicate and deal with the problem when they request it back.
For basic customers, do the same, but generate a unique key for them if it is not supplied. Allow the customer to query your db to get the key if they forget it.