Can the API docs be updated to show relevant fields only?

Question

question

brokenoval asked Jul 11, '20 David Marginian Deactivated commented Jul 13, '20

Can the API docs be updated to show relevant fields only?

Hi guys,

So ultimatly I'm trying to create an order, with items (some with modifiers) and apply a payment through the API.

If you look at the POST /orders API it shows that to create an order you can add (amongst many things):

lineItems,
lineItems.modifications,
payments

However after a lot of trial and error (there are no error or warning messages), I found out that you cannot add lineItems when creating an order.

So I've set up a second API call to POST /orders/:orderId/bulk_line_items which contains the parameter

modifications

But it doesn't work (no error or warning messages). So now I have to do multiple calls to POST /line_items/:lineItemId/modifications - one for every individual line item in the order.

Additionally I have to do a POST orders/:orderId/payments to apply a payment to the original order.

So after many, many hours of trial and error and digging through the community I've figured out that I have to do a minimum of 4 network requests (more for each item in an order) to achieve what the documentation would have you believe you can achive in a single request.

Of course the functionality would be great to do this in one request, but for the moment I'd suggest removing the fields from the documentation that actually don't apply or are irrelevant.

There are a couple of questions related to this from a couple of years ago where this sort of functionality was logged. Do you have any updates on whether this is going to become avaialble?

https://community.clover.com/questions/559/adding-line-items-with-modifiers-using-api.html

https://community.clover.com/questions/20256/is-there-a-way-to-add-modifiers-in-bulk-1.html

REST API

10 |2000

Attachments: Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

Welcome to the
Clover Developer Community

Answer 1 · 2020-07-11T02:45:08Z

David Marginian Deactivated answered Jul 11, '20 David Marginian Deactivated commented Jul 13, '20

Coincidental timing, a few recent (one and two) posts got me investigating very similar issues.

I found an old write-up on the modifiers update issue. I did a bit of investigation and wrote up a strong case that supports us needing to improve our API to allow modifiers to be updated in the bulk line items endpoint. We will see what happens but it looks like it will be a tremendous reduction in requests for us as well as a big win for developers if we can support this. I probably don't understand all of the complexities involved but I'm hopeful that something can be done.

Next, I looked at the documentation issue. Unfortunately, this one is challenging to fix. We have a ton of publicly exposed endpoints. Because of that our documentation is generated, and there are some issues with the generation that are not trivial to fix.

I'm going to link your thoughts here to the issues I have created/commented on. Thanks for the feedback, I hear your frustrations and empathize with you. I am really pushing for something to be done about these issues.

2

10 |2000

Attachments: Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

brokenoval commented · Jul 12, 2020 at 10:44 PM

Thanks David, much appreaciated. Yes definitely adding the modifiers to the bulk_line_items and even the POST line_items will take out the bulk of the requests. A simple enough order can easily result in >10 network requests at the moment which creates a lot of lag, and from a Clvoer perspective a lot of incoming requests, rate limit considerations and DB writes.

I understand the documentation issue, it does look a copy and paste for each resource endpoint in the swagger docs though. One consideration with regards to this is that it makes the documentation page extremely large and navigating through it currently is quite taxing on a browser and does take some time. The network request to retrieve the document for example takes about 5-10 sec, but actually rendering it into the browser takes over 2 x that time:

0 ·

1594593602899.png (158.8 KiB)

David Marginian ♦♦ brokenoval commented · Jul 13, 2020 at 06:16 PM

Yep, I know. I have shared your inputs with the doc team and I am hoping they can find some sort of fix for this.

0 ·

question