Clean up API docs, add authentication tutorial#4341
Clean up API docs, add authentication tutorial#4341micshar92 wants to merge 4 commits intoopenboxes:feature/upgrade-to-grails-3.3.10from
Conversation
|
Thanks @micshar92. Fwiw, I was planning to merge your glossary changes once I found some time. But I just realized that our Read the Docs build integration is no longer working so I need to fix that before merging any doc PRs. |
|
I've fixed the RTD build integration yesterday. Once merged, we'll have the develop branch working again and I'll need to cherry-pick those changes over to the Grails 3 branch. |
|
To answer your questions ...
We currently support eq, like, ilike. I can't remember what property types are supported. It would be straightforward to support other operations and property types, but we haven't encountered a use case for them yet. Perhaps we could provide a link to the GitHub Create Issue form to let developers specify what they'd like to see. But fwiw, I would like to deprecate the Generic API once we move to Grails 3 and have the ability to implement REST APIs through annotations.
The distinction is that the examples use the Generic Product API so we say "product" there to be specific. But the Generic API is potentially being invoked against other resources (category, order, shipment, shipment item) so we use the more generic "object" to refer to the actual objects we're manipulating. If that's confusing you could potentially call them "resource instances" or "resource objects".
Here's an example
I do not remember. |
|
@jmiranda Changes made. 99% done, but before I upload it, one last question: can DELETE be used on more than just single products? (say I want to delete a stocklist or a hold bin, for example) |
No. The DELETE endpoint (unlike UPDATE) only handles one resource instance at a time. |
|
@jmiranda Second draft up. Thanks for the DELETE. In retrospect, it's obvious. My cURL is rusty, since I don't have many opportunities to use it. By the way, big change alert: see the "Create a new shipment" header on generic.md. I felt a more useful alternative to "pass an empty JSON object into the request to see what fields are required" was to list the requirements— name, origin, destination, expectedShippingDate, and shipmentType— and then give a sample request to show how to input each required field. Please check my code to make sure it's correct. |
|
I mistakenly deleted the head repo for the glossary, #4285, before it was merged. Anyway, here's the glossary again, and a few other small fixes. Should be all.
|
|
Sorry for the long delay @micshar92. We are finishing up a very large refactoring project at the moment, so I haven't done a final review on this yet. I will get back to it after the Thanksgiving break. Thank you again for your work on this. |
|
Temporarily closing PR until we have time to work on it. |
|
@micshar92 I finally have the docs almost ready to publish. I'd love to reopen this PR and try to get it merged over. Let me know if you'd like to take that on. Here's the draft version. |
|
@jmiranda I sent you an email, assuming your email is the one listed on your profile page. The title is "About PR 4341", from a Proton Mail account. |
Hey, there! @jmiranda and I agreed in #4235 that the Overview, Getting Started, Generic API, and Searching pages need to be updated. So here, I transformed "Overview" into "Authentication," merged the Generic API and Getting Started pages, and did some minor edits to Searching.
I'm almost done, but I still have some questions so I can carve out this doc. Please help!
(I'll move this part over to lookup.md when it's done.)
(on generic.md) Did I use "product" and "object" correctly here? They're not interchangeable, to my knowledge.
(on generic.md)
DELETEis listed as a cURL operation for the generic API, but it's not documented. I need a sample command and output, please.(on lookup.md) "Searching in stocklists supports filtering by
name,requisitionNumber,origin.id,destination.idas well as other attributes to be documented at a later time." What are these other attributes?Thanks for helping!