Skip to content

Clean up API docs, add authentication tutorial#4341

Closed
micshar92 wants to merge 4 commits intoopenboxes:feature/upgrade-to-grails-3.3.10from
micshar92:feature/upgrade-to-grails-3.3.10
Closed

Clean up API docs, add authentication tutorial#4341
micshar92 wants to merge 4 commits intoopenboxes:feature/upgrade-to-grails-3.3.10from
micshar92:feature/upgrade-to-grails-3.3.10

Conversation

@micshar92
Copy link

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!

  1. (on generic.md) "Support for other property types (Integer, Date, BigDecimal) and operators (i.e. in, isNull, between, gt, ge, lt, le, etc) will be added at some point in the future. In addition, there's no way to perform nested searches (i.e. search for all shipment items that reference a particular product) at this time so please " Does OpenBoxes support these property types and operators mentioned? Does it have nested search functionality since the last writing?

(I'll move this part over to lookup.md when it's done.)

  1. (on generic.md) Did I use "product" and "object" correctly here? They're not interchangeable, to my knowledge.

  2. (on generic.md) DELETE is listed as a cURL operation for the generic API, but it's not documented. I need a sample command and output, please.

  3. (on lookup.md) "Searching in stocklists supports filtering by name, requisitionNumber, origin.id, destination.id as well as other attributes to be documented at a later time." What are these other attributes?

Thanks for helping!

@micshar92 micshar92 marked this pull request as draft October 18, 2023 21:51
@jmiranda
Copy link
Member

jmiranda commented Oct 19, 2023

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.

https://readthedocs.org/projects/openboxes/builds/22279630/

@jmiranda jmiranda changed the base branch from feature/upgrade-to-grails-3.3.10 to develop October 22, 2023 15:29
@jmiranda jmiranda changed the base branch from develop to feature/upgrade-to-grails-3.3.10 October 22, 2023 15:29
@jmiranda
Copy link
Member

I've fixed the RTD build integration yesterday.
https://readthedocs.org/projects/openboxes/builds/22299207/

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.

@jmiranda
Copy link
Member

To answer your questions ...

Does OpenBoxes support these property types and operators mentioned? Does it have nested search functionality since the last writing?

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.

(on generic.md) Did I use "product" and "object" correctly here? They're not interchangeable, to my knowledge.

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

(on generic.md) DELETE is listed as a cURL operation for the generic API, but it's not documented. I need a sample command and output, please.
It's just using the DELETE method

DELETE /openboxes/api/generic/product/:id

Here's an example

curl -b cookies.txt -X DELETE https://openboxes.ngrok.io/openboxes/api/generic/product/<id>

(on lookup.md) "Searching in stocklists supports filtering by name, requisitionNumber, origin.id, destination.id as well as other attributes to be documented at a later time." What are these other attributes?

I do not remember.

@micshar92
Copy link
Author

micshar92 commented Oct 23, 2023

@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)

@jmiranda
Copy link
Member

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.

@micshar92
Copy link
Author

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

@micshar92
Copy link
Author

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.

  • the glossary's CSS is now the same orange as the knowledge base, for continuity.
  • The Support page now has a link to the knowledge base and lists professional services offered without having to click over to that corresponding page.

@jmiranda
Copy link
Member

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.

@jmiranda jmiranda added the domain: documentation Changes or discussions relating to documentation label Dec 2, 2023
@micshar92
Copy link
Author

@jmiranda I added a small fix to the top of the Stock Movement page to address #4437. Most of it's copy-and-paste from the community site.

@micshar92 micshar92 marked this pull request as ready for review February 29, 2024 16:37
@jmiranda jmiranda added the status: wont do Issues that we will not be addressing but can be revisited in the future label Mar 6, 2024
@jmiranda
Copy link
Member

jmiranda commented Mar 6, 2024

Temporarily closing PR until we have time to work on it.

@jmiranda jmiranda closed this Mar 6, 2024
@jmiranda
Copy link
Member

jmiranda commented Aug 18, 2024

@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.
https://docs.openboxes.com/en/obpih-6197/

@micshar92
Copy link
Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

domain: documentation Changes or discussions relating to documentation status: wont do Issues that we will not be addressing but can be revisited in the future

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants