IPFS is a peer-to-peer (P2P) networking protocol used to share data on the distributed web. You can think of it as a file system with some unique characteristics that make it ideal for safe, decentralized sharing.
If you haven't yet done so, we encourage you to check out our Content Adddressing on the Decentralized Web tutorial to learn all about the decentralized web and how it compares to the web you're accustomed to. There you'll learn all about content addressing, cryptographic hashing, Content Identifiers (CIDs), and sharing with peers, all of which you'll need to understand to make the most of this tutorial.
You can store multiple types of data with IPFS. If you've explored our P2P Data Links with Content Addressing or Blogging on the Decentralized Web tutorial, you've already seen how you can store primitives, objects and arrays on the network using the DAG API.
The DAG API allows you to use the unique and versatile primitive data structures offered by IPLD (InterPlanetary Linked Data) within IPFS. You can recognize its methods in js-ipfs (the JavaScript implementation of IPFS) because they take the following format: ipfs.dag.someMethod()
The DAG API is the most generic and flexible approach to adding data to the IPFS node, but it's not the most efficient when it comes to the very common use case of sharing files. What if you wanted to share a picture of a kitten, or a larger file like a funny video of your favorite celebrity dog? How would you add these files to the network and provide a way for your friends to see them? How should each file be placed in the Directed Acyclic Graph (DAG), in a single block or split into chunks? These are optimization details that fall beyond the scope of the DAG API. Though it would be possible to use the DAG API to add files to an IPFS node, it would be a labor-intensive task.
The Files API, on the other hand, is custom-built for a more specific use case. The Files API prepares files to be placed in the network and ensures that IPFS knows how to access them and handle them efficiently. The Files API is made of two parts: the Regular Files API, which we'll cover in this tutorial, and the Mutable File System (MFS).
If you've read our Mutable File System tutorial, you may be thinking, "I've already learned how to work with files on IPFS. How will this be any different?"
The Mutable File System (MFS) provides an API designed to replicate familiar file system operations such as mkdir, ls, cp, and others, mimicking the way you organize files and directories on a computer. However, the way that content is addressed in IPFS makes it an immutable file system. The address to a file or directory depends on its contents, so any change to a file or directory will result in an entirely new address. The MFS Files API works on a familiar-looking file system with regular paths — like /some/stuff — in the local IPFS node, which hides the complexity of immutable content addressing.
Although MFS is very useful, the abstraction it provides hides some of the inner workings of IPFS. The Regular Files API we will discuss here is instead a bare bones approach to managing files in IPFS. It trades the powerful abstractions of MFS for a scheme which helps you understand what is actually happening in the file system. In the Regular Files API you'll find methods like add, cat, get and ls.
Unlike the MFS API, which can be recognized in js-ipfs by the format ipfs.files.someMethod(), the Regular Files API uses top-level methods that take the format ipfs.someMethod().
The distinction between these two versions of the Files APIs is a bit confusing at the moment, but the IPFS team is currently working on revamping them to make the whole Files API more user-friendly. We'll be sure to update our tutorials when things change!
Feeling stuck? We'd love to hear what's confusing so we can improve this lesson. Please share your questions and feedback.