Implement POST, PUT and PATCH

[bjohas]

To follow

[retorquere]

It id much better to have a use-case that demands PATCH or PUT than just implementing the method. If the use-case needs it, the backing method comes automatically.

[bjohas]

Implement POST, PUT and PATCH as described here https://www.zotero.org/support/dev/web_api/v3/write_requests#item_requests

What should the syntax be?

zotero-cli items-post file.json
zotero-cli items-put  --key itemKey file.json
zotero-cli items-patch  --key itemKey file.json

or

zotero-cli items --post file.json
zotero-cli items --put  --key itemKey file.json
zotero-cli items --patch  --key itemKey file.json

Note: The item's current version number is included in the version JSON property, as well as in the Last-Modified-Version header of single-item requests. PUT and PATCH requests must include the item's current version number in either the version property or the If-Unmodified-Since-Version header. (version is included in responses from the API, so clients that simply modify the editable data do not need to bother with a version header.) If the item has been changed on the server since the item was retrieved, the write request will be rejected with a 412 Precondition Failed error, and the most recent version of the item will have to be retrieved from the server before changes can be made.

[bjohas]

True - but if you do the POST, PUT, PATCH, then I could do the add_items tags?

But if you prefer, close this one, and open the add_tags one?

[bjohas]

It's just that I was going through the headings (as agreed) and comparing against the Zotero API, finding that many of the interactions offered by pyzotero are convenience methods that build on API calls.

It would be good to implement the primary API calls, because that gives me the examples to work with.

However, I'm easy - you could re-open the three referenced requests instead. I guess they would be very similar?

[retorquere]

It's just that having an actual use-case makes it easier to make good choices for what to hide and what to expose. If it's just "implement POST" I could just hand you a request-promise object and you'd have the implementation. I've added POST and new-item creation, I'll look at those use-cases for PATCH and PUT

[retorquere]

The headings I meant as an inspiration of what kind of functionality you want and the corresponding CLI option.

[bjohas]

Ah ok - sorry, I didn't quite get that.

So yes, the use cases are as above:

• I want to be able to add tags to an item: That's a PATCH, as I don't care about the other properties.
• I want to be able to update an item. Step 1: retrieve item. Step 2: PUT.
• I also want to be able to download a template and the create an item. POST.

(These are similar of course to the Zutilo functions you built...)

[bjohas]

I've updated my post above, as POST doesn't take an itemKey - it's a new item.

[bjohas]

Example 1:

zotero-cli items --key ABC > json.txt
gedit json.txt
zotero-cli items --put --key ABC json.txt

Example 2:

gedit tags.json
zotero-cli items --patch --key ABC,DEF,GHI tags.json

Example 3

zotero-cli --template book > book.json
gedit book.json
zotero-cli items --post book.json

("--template X" calls "GET /items/new?itemType=X" )

[retorquere]

See npm start -- create-item -h

[bjohas]

Thanks! Will look now!

Are the examples helpful?

[retorquere]

I could make it items --post but the behavior of items is getting to be a CLI on its own

[bjohas]

Fine!

[bjohas]

For example, a user guide would say: Here is how you use create item:

zotero-cli create-item --template book > book.json
gedit book.json
zotero-cli create-item book.json

For further options, see zotero-cli create-item --h.

If that's right, then the first command doesn't work fully: "zotero-cli.ts: error: Need at least one item to create". I.e. - if I understand correctly - "--template" should not require file.json, but perhaps even complain if you try to specify json at the same time?

[bjohas]

I'm adding some documentation here: https://github.com/edtechhub/zotero-cli/blob/master/docs/COMMANDS.md

[retorquere]

That seems just like a copy of the Zotero API docs?

You can add docs to the command methods by adding/editing a comment like /** .... */ at the top of the method, and my adding help: ... to the addArgument calls.

[retorquere]

--template is fixed

[retorquere]

patch added.

[bjohas]

Thank you!

Yes, some of it comes from the Zotero API docs, but the last column is the commands for zotero-cli.

[retorquere]

This is in the end your call but it seems to me a CLI should be task-focused instead of just replicating the API. Otherwise I could have just left it at implementing post, patch, etc and be done.

[bjohas]

Opened issue for documentation here: https://github.com/edtechhub/zotero-cli/issues/89