Web API best practices inserting data: nested or per entity

Question

Assume that you have the following 3 entities:

• Manual
• Version
• Document

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?

• Robert Harvey: I don't understand this question: "Do I accept the posted data object in a nested XML/Json structure, or do I want the customers to add the data entity per entity?" Can you clarify?
• Robert Harvey: Should I store his reference numbers or should he store mine for future updates, deletes and related inserts? -- That depends on whether you need to access his database, or he needs to access yours, or both.
• Zeep: What I mean is, do I allow the user to send data of all 3 entities nested in 1 post object at once, or do I want the customer to first insert a Manual record, followed by a Version record and then eventually a Document record? I only want customers to send data, I won't be inserting or updating data on their end.
• Robert Harvey: I would think the driver for that is, what do you want your API to look like?

Answer 1

• Do I accept the posted data object in a nested XML/Json structure, or do I want the customers to add the data entity per entity

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.

• Should I store his reference numbers or should he store mine

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.

Answer 2

Do I accept the posted data object in a nested XML/Json structure:

I think you should only do this if there is a requirement to do bulk inserts or updates. However if otherwise you shouldn't, and build a simple REST API. If you want to support bulk operations in the future you can always provide a new Api call. Further Implementing bulk API complicates things if you want customer to store your primary key as you need to send a complicated response with primary key to the each new item inserted.

Should I store his reference numbers or should he store mine

You should definitely store customers reference number. Unless customer want to use your reference number for the get requests, I don't think there's much use storing your primary key in customers system.