About `PublishedSeqAppendOnlyData.resolved_from`

I’m using the FilesContainer returned by fetch() on a public website. Most of the structure is fairly self explanatory but I have a couple of questions.

Looking at the following subset of FilesContainer:

PublishedSeqAppendOnlyData.resolved_from.type_tag   // 1500

PublishedSeqAppendOnlyData.type_tag   // 1100

I’m assuming that the first group of properties relate to the public name and the second to the FilesContainer itself but am not sure, and also confused as to how to reference each.

My use case at the moment is to provide an ETag for the container that is being returned from a safe.fetch() such as safe.fetch('safe://dweb/'), safe.fetch('safe://dweb/blog') etc

An ETag is an HTTP response header (a string) that is guaranteed to change if the resource being retrieved is different from a previous fetch, and the same otherwise. So using an xor URL seems ideal for this, as that should always change if the root or any sub-path of it changes. Or does it?

What I’m not sure about is which value to use for the ETag, and whether to add a version string to the end of the URL. At the moment I have the following:

ETag = filesContainer.resolved_from.xorurl

This relates to the public name rather than the container, but any change to the latter should I hope change the xorurl of the public name. But I’m not sure if that’s the case, and if not whether just adding the version string (e.g. ‘?v=0’) would make it so.

Two questions:

  • I’m wondering if really what I need is a URL based on filesContainer.xorname, in which case I need to know how to convert that into a safe URI (asked in this post)?
  • in either case, I’m not clear if the safe xor URI factors in the version or if I would also need to append ?v=n when the fetch is for safe://dweb/ and the same question for a sub-container such as safe://dweb/blog/?

That’s correct.

The xorurl to specific resources may change, but the xorurl of the container will stay the same. It just has new information appended to it (which we read as a later version).

You should use resolved_from.version if you’re looking at the site at an NRS name. If you’re looking at a specific FilesContainer (which may or may not be referenced from an NRS name), then you’d want the PublishedSeqAppendOnlyData.xorname.

It can be confusing, as a NRS name AOD maye point to a FilesContainer version, but not the FilesContainer in general (which would retrieve the latest always). So a FilesContainer can be updated and a given NRS name may know nothing about this.

Ie. you may want to update the files container, but not update your website. You have to opt in to do this via cli (with the -u flag when syncing to a NRS url, to update that NRS url container as well)

To specify a version you must append the ?v=x to the xorurl. Anything else will grab the latest.

(Just checking out your Q re: conversion now, will respond over there)

1 Like

Thanks Josh, very helpful. Starting to get the hang of this I hope :slight_smile: Thinking out loud…

  • The ETag for the root folder of a website should be based on the resolved_from.xorurl + NRS name version. This means that if the content of the root folder changes the ETag will change. It will also change if the content of a subfolder changes, but that’s an inefficiency that will not affect many use cases.
  • A subfolder of a website which is just a path inside the root FilesContainer should also use the above, because if the content is changed the version will change. The above inefficiency might be more of an issue here if there’s a subfolder being monitored and it is being flagged as changed unnecessarily (ie the ETag changes because something unrelated is being updated frequently).
  • A file resource should always point to an Immutable Data, so it should be ok to use the xorurl of the file itself for its ETag.

Note: The inefficiencies noted in the first two bullets are specific to RESTful HTTP interfaces implemented on top of the APIs, but I expect will resurface if the SAFE APIs add their own change notification or monitoring, so might be worth thinking about wrt FilesContainer etc.


  • I imagine the APIs might need to support subfolders which are not just paths, but paths which resolve to another FilesContainer. Is that so?
    • if so I’m curious as to how this will be represented in the API (e.g. the returned FilesContainer).
    • If not, can we still represent empty folders within a FilesContainer without them resolving to a resource?

Yep, as its versions of the site (ie, changing the stylesheet could drastically change the info displayed on a site).

This may work now. Just the link will have to be versioned as above…

Hmmm, i think right now the only way to create a container is via uploading files. As it’s just a doc in itself that should be possible to do without uploading files later on. We just need to extract that API…

1 Like

True, but a website is one use case whereas this is an API for a storage system, not just websites.

Thanks for the other answers. Sounds like empty containers are supported :white_check_mark: but not available in the API yet. :slight_smile:

It may be, but if it’s public/pWeb then it should follow the same rules, no?

Interesting point. It requires me to change how I’m thinking about this (which is hard), but maybe you have a convert! Not sure so I’ll chew that one over. Thanks :slight_smile:

Thoughts @bzee?