1

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?

  • 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 Jan 23 '18 at 16:45
  • 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. – Robert Harvey Jan 23 '18 at 16:46
  • 1
    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. – Zeep Jan 23 '18 at 16:53
  • I would think the driver for that is, what do you want your API to look like? – Robert Harvey Jan 23 '18 at 17:55
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.

1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.