Ben Langhinrichs

Photograph of Ben Langhinrichs

E-mail address - Ben Langhinrichs







Recent posts

Fri 31 Jan 2020

Next week seems like a good time



Thu 30 Jan 2020

Branching out: No REST for the wicked - Part 2



Wed 22 Jan 2020

Branching out: No REST for the wicked - Part 1


February, 2020
SMTWTFS
      01
02 03 04 05 06 07 08
09 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 29

Search the weblog





























Genii Weblog

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.
 
Inline JPEG image
 
 
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.
 
Inline JPEG image
 
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:
 
Inline JPEG image
 
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. 
 
Inline JPEG image
 
 
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 
 
Inline JPEG image
 
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:
 
  1. Do you want to maintain the integrity of the rich text? Try to use PATCH (unless you need to change the rich text itself).
  2. Do you want to delete fields, not just blank them out? You'll need to use PUT and leave those fields out. 
  3. 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:
 
Inline JPEG image
 
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:
 
Inline JPEG image
 
When I press Send, I get a 400 code, an error. The JSON result shows:
 
Inline JPEG image
 
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:
 
Inline JPEG image
 
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.

What has been said:


1104.1. Theo Heselmans
(01/30/2020 01:14 PM)

Nicely done, Ben.

I discovered the difference between PUT and PATCH early on myself. I doubt there’s any real live situation where you want to use PUT, and ‘forget’ all fields not mentioned in the JSON data.

Thanks for this series.

I wished you could have joined us at Engage to tell people IRL about your ‘musings’.


1104.2. Ben Langhinrichs
(01/30/2020 02:53 PM)

I wish I could have made it to Engage. I'd love to come over some time, but am busy busy busy.

As for PUT vs. PATCH, while I can come up with artificial reasons for using PUT, I'd agree that in real use PATCH is virtually always what you need.


1104.3. Stephan Wissel
(02/02/2020 11:36 AM)

That's the little beef I have with the current REST endpoints. As long as you have author access you can change any field including the computed ones. But that doesn't need to KEEP that way ;-)

Have your say:

Name *:
E-mail:
e-mail addresses will not be displayed on this site
Comment *:


<HTML is not allowed>
Linking: Add links as {{http://xxx|title}}, and they will be activated once approved
Blocked? Unable to post a comment? Please read this for a possible explanation...