Web API best practices inserting data: nested or per entity

by Zeep   Last Updated January 23, 2018 17:05 PM

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?



Answers 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.

Ewan
Ewan
January 23, 2018 16:58 PM

Related Questions


Including aggregate data in REST response in DDD

Updated February 16, 2018 11:05 AM