Document patch()

[jeff-zucker]

Currently in 1.0.0 the default (high-level) behavior of both createFile() and updateFile() is to call putFile making them both equivalent to createOrReplaceFile(). I suggest we have a real updateFile(), in other words, we support PATCH so that users can make atomic changes to the content of a file without completely replacing it. I would guess we'd want a SolidApi.patch() method and call it from SolidFileClient.updateFile(). @bourgeoa. @Otto-AA Thoughts?

[bourgeoa]

The name updateFile is very confusing, It was widely used in solid-file-client as a replacement to putFile.
I prefer something like patchFile.

[Otto-AA]

Regarding putFile: I think it depends on how much custom logic you want. If updateFile would only forward to putFile, then why not directly use putFile and remove the alias?

Regarding patch: Do you think that PATCH would be a high or low level method? I'd guess that those persons who know how to use it will know it as "PATCH" and hence I'd use patch(File) as a name. If you want to add additional behavior (more than just making a PATCH request) we should find a different name though.

[jeff-zucker]

I don't see update/patch as doing anything other than patch no matter what we call it. rdflib.js uses update() to do a patch so I am okay with using either verb. Update seems more on the same level as read and create, but I don't feel strongly about this.

…

On Wed, Dec 4, 2019 at 2:00 PM A_A ***@***.***> wrote: Regarding putFile: I think it depends on how much custom logic you want. If updateFile would only forward to putFile, then why not directly use putFile and remove the alias? Regarding patch: Do you think that PATCH would be a high or low level method? I'd guess that those persons who know how to use it will know it as "PATCH" and hence I'd use path(File) as a name. If you want to add additional behavior (more than just making a PATCH request) we should find a different name though. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#97?email_source=notifications&email_token=AKVJCJD35HEVZ65KX5CMF63QXASAFA5CNFSM4JVM5YKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEF6USBI#issuecomment-561858821>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKVJCJFPNIQOBBPBKDW3C73QXASAFANCNFSM4JVM5YKA> .

[bourgeoa]

@Otto-AA @jeff-zucker
I am going to make a patchFile()

Going in NSS through :

• patch.js
• patch-sparql-update-tes.js and patch-test.js

Only 3 SPARQL verbs are allowed : INSERT/DELETE/WHERE

There appears to be 2 ways to make a patch. Both allow using prefixes.

• a turtle content and a contentType = application/sparql-update

        @prefix solid: <http://www.w3.org/ns/solid/terms#>.
        @prefix : <#>.
        @prefix ex: <http://example.com#>.
        <> solid:patches <urlToPatch>;
             solid:inserts { <> ex:temp 245 . };
             solid.deletes { <> ex:temp 200 .}.

• or a N3 text content with a contentType=text/n3

        @prefix ex: <http://example.com#>.
        INSERT { :test1 ex:temp :321; ex:temp1 :322, :300 .}
        DELETE { <#test> :temp :245. }
        DELETE { <> a :test. }

the function could be : patchFile(urlToPatch, patchContent, patchContentType, options)

What check do we introduce knowing that NSS does a lot of tests:

• if urlToPatch do not exist it is created. It is like a PUT
• contentType can only be application/sparql-update or text/n3
• insert or delete is needed
  .....

I think we could check that urlToPatch has a text/turtle extension .acl, .meta, .ttl and nothing else

[jeff-zucker]

This will be a great addition. Thank you.

Yes, I think your syntax for the method is good.
All of the checks you mention make sense to me.
Do you need anything else on my end? I plan to be more available, so ping me at any time.

[bourgeoa]

see PR #170