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?

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.