Branching out: No REST for the wicked - Part 2
Thu 30 Jan 2020, 12:25 PM
by Ben Langhinrichs
Previous posts in this series:
This is a continuation of my post from a week ago (see Part 1 above) about Domino Web Services as a REST API for doing CRUD (or really ARCUD, Access/Read/Create/Update/Delete) operations on Notes documents.
3) Update - Getting the contents of a Notes document and all its fields in JSON
Updating a document is quite similar to creating one. For Create, you'll recall that we did a POST to a URL endpoint of /UseCases.nsf/api/data/documents with a JSON payload and the Content-Type of application/json.
You may recall that I made a mistake the first time, and tried to POST to a URL endpoint which included the original document I had copied.
That failed because I could not POST a document to that URL, but it provides an excellent clue as to how we update or modify the document. If we had the correct Content-Type and the exacty same URL endpoint as above, but switched the the from POST to PUT, it would have updated the original document. We would not have a new document, but rather just a new Subject (since that is all that changed) on the old document.
So:
- POST - Create a new document
- PUT - Update an existing document, replacing all values.
But it turns out there is another option for updating. Think of it this way. While the PUT message updates a document, it does it by replacing all the fields on the document and keeping the same UNID. That's handy when you have all the fields, but what if I just want to change the Subject (as you may, too, when we talk about this geeky stuff), but I don't have all the other fields. I could do a GET first, then change the value for Subject and then PUT, but an easier and safer way is to only pass the new Subject value and use PATCH instead of PUT. This will leave all existing fields alone except the ones explicitly included.
So:
- POST - Create a new document
- PUT - Update an existing document, replacing all values.
- PATCH - Update an existing document, replacing only included values.
-
Let's give this a try. When we left off, we had the view:
We did GET to read all the fields from the Better Budgies document, then editedg the Subject to be "Better Budgies 2", then did a POST to create a new document with a new UNID and everything. But we still have that "Better Budgies" document, and just the way World War I was only called that after World War II, let's update the "Better Budgies" subject to "Better Budgies 1".
I created a new PATCH message, set the Content-Type to application/json, set the URL endpoint to the exact same one I'd used for the get, and created a body with just the enclosing braces (required) and the new Subject.
I pressed Send, and got a 200 status, meaning it was accepted (but not created, which was 201). When I look at the view, I see the modified "Better Budgies 1" document.
When I open it up, I see
You may not notice immediately, but a critically important part of this update is that the rich text is unchanged. It didn't have to get converted to HTML and back, so it still has its full integrity.
Choosing PUT or PATCH:
- Do you want to maintain the integrity of the rich text? Try to use PATCH (unless you need to change the rich text itself).
- Do you want to delete fields, not just blank them out? You'll need to use PUT and leave those fields out.
- Do you only know some of the fields (perhaps because some are hidden)? Use PATCH so you don't disrupt those fields.
Speaking of which, I switch from PATCH to PUT with this exact same message and hit Send. Still a 200 code, so it worked, but when I look at the document:
So, be careful with that PUT message type!
4) Delete - Getting rid of a Notes document
We might as well get rid of "Better Budgies 1", since it has nothing but a Subject now. For this, we'll switch to the Delete message type, but use the same URL endpoint.
I am not including any JSON payload or any Content-Type, just the URL and the DELETE type:
When I press Send, I get a 400 code, an error. The JSON result shows:
This is a reminder that while I opened the ACL up fairly wide, I did not allow Anonymous to delete documents, and all of this is running as Anonymous. So, error checking on the result is importamt. But after I give Anonymous the right to delete documents and press Send again, I get the 200 OK code. Now, my view looks like this:
To recap, we covered ARCUD all the way:
Access - we used GET to Access the documents through the collection with just the URL endpoint
Read - we used GET again to Read the document as a JSON payload with the URL endpoint (though we could have used Accept header)
Create - we used POST to Create the document with a JSON payload and Content-Type header
Update - we used PUT and PATCH with a JSON payload and Content-Type header
Delete - we used DELETE with just the URL endpoint
There is plenty more to talk about such as authentication and variations on how the data is returned, but this should get you started with Domino Web Services. Next up, the AppDev Pack with Proton and domino-db classes for Node.js. Stay tuned (same Bat time, same Bat channel).
Copyright © 2020 Genii Software Ltd.