Fetch-IPFS.md
1 # Fetch API for `ipfs://` and `ipns://` 2 3 This API is implemented in [js-ipfs-fetch](https://github.com/RangerMauve/js-ipfs-fetch). 4 5 ## Example 6 7 ```javascript 8 // Upload some data to IPFS 9 const response1 = await fetch(`ipfs:///index.html`, { 10 method: 'POST', 11 body: ` 12 <!DOCTYPE html> 13 <marquee> 14 Hello World! 15 <marquee> 16 Hello World! 17 <marquee> 18 Hello World! 19 </marquee> 20 </marquee> 21 </marquee> 22 ` 23 }) 24 25 const url = await response1.text() 26 27 // Should look like this: 28 // ipfs://k2jmtxw856nqrm9pc7up4acmbtco1muuenxjy1lkv9x6rsxd1zclki9m/index.html 29 console.log('IPFS URL:', url) 30 31 // You can load the data back up 32 const response2 = await fetch(url) 33 34 console.log('Uploaded content', await response2.text()) 35 36 // Get the root of the new IPFS site you created 37 // This with automagically serve the `index.html` file when you navigate to it 38 const root = new URL('/', url).href 39 40 // Publish to IPNS 41 // `ExampleName` can be any name, it'll be used to generate a keypair 42 // Instead of exposing private keys directly, you can use the key names wherever you need 43 const response3 = await fetch(`ipns://ExampleName`, { 44 method: 'PUBLISH', 45 body: root 46 }) 47 48 // Should look something like this: 49 // ipns://k2jmtxu20rj3axf43s36u7r9ds7fsgy5djbdxmuhnfyan2dgom9cil72/ 50 // Every time you PUBLISH a new version, the URL will stay the same for the given key 51 const ipnsURL = await response3.text() 52 53 console.log('Published URL', ipnsURL) 54 ``` 55 56 ### `await fetch('ipfs://CID/example.txt')` 57 58 If you specify a URL for a file (no trailing slashes), it will be loaded from IPFS and the content will be sent as the response body. 59 60 The response headers will contain a `Content-Length` header set to the size of the file. 61 62 ### `await fetch('ipfs://CID/example/')` 63 64 If you specify a URL for a folder (has a trailing slash), the folder will be enumerated from IPFS and an HTML page listing its various files will be rendered. 65 66 Hyperlinks to files/folders will be automatically generated as relative URLs. 67 68 Links will have a trailing slash for folders. 69 70 If the folder contains an `index.html` it will be served as a file instead of performing a directory listing. 71 72 ### `await fetch('ipfs://CID/example/', {headers: {'X-Resolve': none}})` 73 74 If you specify the `X-Resolve: none` header in your request, the resolution of `index.html` will be ignored and a directory listing will always be performed. 75 76 ### `await fetch('ipfs://CID/example/', {headers: {Accept: 'application/json'}})` 77 78 If you specify a URL for a folder, and set the `Accept` header to only contain `application/json`, the directory will be enumerated and the list of files/folders will be returned as a JSON array. 79 80 You can get the file/folder list out of the response using `await response.json()`. 81 82 Names will have a trailing slash for folders. 83 84 ### `await fetch('ipfs://CID/example.txt', {method: 'HEAD'})` 85 86 If you set the method to `HEAD`, it will be like doing a `GET` request but without actually loading data. 87 88 This is useful for getting the `Content-Length` or checking if a file exists. 89 90 ### `await fetch('ipfs://CID/example.txt', { headers: { Range: 'bytes=0-4' })` 91 92 You can specify the `Range` header when making a request to load a subset of a file. 93 94 ### `await fetch('ipfs:///example.txt', {methhod: 'post', body: 'Hello World!'})` 95 96 You can upload files to IPFS by using `POST` messages. 97 98 The response body will contain the `ipfs://` URL for your data. 99 100 Please open a GitHub issue if you have ideas for how to support multiple files in a fetch-compliant way. 101 102 ### `await fetch('ipns://CID/example.txt')` 103 104 You can specify an IPNS URL to have it resolve to whatever resource you wanted using the Inter-Planetary Naming System 105 106 ### `await fetch('ipns://self', {method: 'publish', body: 'ipfs://CID/example.txt'})` 107 108 You can publish to IPNS using the `PUBLISH` method. 109 110 The `body` should contain the `ipfs://` URL you want to point to. 111 112 The response will be an `ipns://` URL for your data. 113 114 It's best to point at directories when possible so that they can be treated as origins within browser contexts. 115 116 Specify the key name in the `origin` portion of the ipns URL. 117 If the key doesn't exist, it will ge generated. 118 119 Please open a GitHub issue if you have ideas for how to do key import and export.