neocities/views/api.erb

<div class="header-Outro">
  <div class="row content single-Col">
  <h1>Neocities Developers API</h1>
  <h3 class="subtitle">Make changes to your site remotely with programming languages!</h3>
  </div>
</div>

<div class="content single-Col misc-page">
  <h2>Ideas</h2>
  <p>
    <ul>
      <li>Create your own blog, and use a script to add new blog posts.</li>
      <li>Integrate external HTML editors / upload tools.</li>
      <li>Provide updated air quality information from a gauge at your house.</li>
      <li>Conduct regular backups of your site.</li>
    </ul>
  </p>

  <h2>Rules</h2>
  <p>
    <ul>
      <li>Do not spam the server with tons of API requests.</li>
      <li>Try to limit recurring site updates to one per minute.</li>
      <li>Do not use the API to "game" the site (increase ranking by manipulating our algorithms, or constantly updating your index.html with the same content). Sites caught doing this will be de-listed from the browse page.</li>
      <li>Do not use the API to data mine / rip all of the sites.</li>
    </ul>
  </p>

  <h2>Command Line Usage</h2>
  <p>
    If you're just looking for a command line interface to the API, <a href="/cli">go here</a>.
  </p>

  <h2>Libraries</h2>
  <p>
    There are client libraries available for popular programming languages to make it easier to work with the API:
    <ul>
      <li><a href="https://github.com/neocities/neocities-node" target="_blank">Node.js / JavaScript</a></li>
      <li><a href="https://github.com/aergonaut/neocitizen" target="_blank">Ruby</a> - contributed by <a href="https://twitter.com/aergonaut" target="_blank">Chris Fung</a> 👨‍💻</li>
      <li><a href="https://github.com/neocities/python-neocities" target="_blank">Python</a> - contributed by <a href="https://github.com/soulshake" target="_blank">AJ Bowen</a> <code style="margin-left: 20px">$ curl cv.soulshake.net</code></li>
      <li><a href="https://github.com/peterhellberg/neocities" target="_blank">Go</a> - contributed by <a href="https://twitter.com/peterhellberg" target="_blank">Peter Hellberg</a> 🧗</li>
      <li><a href="https://github.com/seankross/neocities" target="_blank">R (statistical language)</a> - contributed by <a href="https://twitter.com/seankross" target="_blank">Sean Kross</a> 📚</li>
      <li><a href="https://github.com/kambrium/neocitiesd" target="_blank">D</a> - contributed by <a href="http://martinmuehlbauer.com" target="_blank">Martin Muehlbauer</a> 🏝️</li>
      <li><a href="https://github.com/reed-jones/Neocities-php" target="_blank">PHP</a> - contributed by <a href="https://www.reedjones.com" target="_blank">Reed Jones</a> 🇨🇦</li>
    </ul>
  </p>
  <hr>
  <h1>API Documentation</h1>
  <p>
    The Neocities API is a <a href="http://en.wikipedia.org/wiki/Representational_state_transfer" target="_blank">REST</a> API, which uses query parameters for input, and returns data in the <a href="http://en.wikipedia.org/wiki/JSON" target="_blank">JSON</a> format (except for file downloads). It uses client-side <a href="http://en.wikipedia.org/wiki/Basic_access_authentication" target="_blank">HTTP AUTH</a> to authenticate, using your user/site name and password as the credentials. It is designed to play nicely with the most common HTTP libraries available in programming languages, and can be easily used with <strong>cURL</strong> (a command-line tool for making HTTP requests you can use by opening a terminal on your computer).
  </p>
  <p>
    <strong>That's a lot of buzz words if you're new to programming.</strong> Don't worry, it's easier than it sounds! We'll walk you through some working examples you can get started with.
  </p>

  <h2>POST /api/upload</h2>
  <p>
    Uploads files to your site. You can upload as many files as you want with a single query, as long as the entire request stays within the disk space limit. The parameter name should be the name of the file, with the extension so we know what kind of file it is (index<strong>.html</strong>).
  </p>

  <h3>Examples</h3>
  <h6>Using cURL</h6>
  <p>Upload a single local file (<strong>local.html</strong>), which will be named <strong>hello.html</strong> on your site:</p>
  <pre><code class="bash">$ curl -F "hello.html=@local.html" "https://USER:PASS@neocities.org/api/upload"</code></pre>

  <h6>Using Node.js</h6>
  <p>This example uses the <a href="https://github.com/neocities/neocities-node" target="_blank">neocities</a> module. You can install it by running <strong>npm install neocities --global</strong> in your terminal.</p>
  <pre><code class="javascript">var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.upload([
  {name: 'hello.html', path: './local.html'}
], function(resp) {
  console.log(resp)
})</code></pre>

  <h2>POST /api/delete</h2>
  <p>
    Deletes files from your site. Provide a <strong>filenames</strong> argument with an array of filenames you wish to delete. You can delete any files except index.html.
  </p>
  <p>
    <strong>Be careful with this API call.</strong> There is no way to undo a delete!
  </p>

  <h3>Examples</h3>
  <h6>Using cURL</h6>
  <p>
    Delete <strong>img1.jpg</strong> and <strong>img2.jpg</strong> from your site:
  </p>
  <pre><code class="bash">curl -d "filenames[]=img1.jpg" -d "filenames[]=img2.jpg" \<br>"https://YOURUSER:YOURPASS@neocities.org/api/delete"</code></pre>

  <h6>Using Node.js</h6>
  <pre><code class="javascript">var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.delete(['img1.jpg', 'img2.jpg'], function(resp) {
  console.log(resp)
})</code></pre>
  <h2>GET /api/list</h2>
  <p>
    This call provides a list of files for your site. If you pass no arguments, it will return a list of all files. If you provide a <strong>path</strong> argument, it will return a list of files for the path. Dates conform to <strong>RFC2822</strong>.
  </p>
  <h3>Examples</h3>
  <h6>Using cURL</h6>
  <pre><code class="bash">$ curl "https://USER:PASS@neocities.org/api/list"
{
  "result": "success",
  "files": [
    {
      "path": "index.html",
      "is_directory": false,
      "size": 1023,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "c8aac06f343c962a24a7eb111aad739ff48b7fb1"
    },
    {
      "path": "not_found.html",
      "is_directory": false,
      "size": 271,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "cfdf0bda2557c322be78302da23c32fec72ffc0b"
    },
    {
      "path": "images",
      "is_directory": true,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000"
    },
    {
      "path": "images/cat.png",
      "is_directory": false,
      "size": 16793,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "41fe08fc0dd44e79f799d03ece903e62be25dc7d"
    }
  ]
}
</code></pre>

<pre><code class="bash">$ curl "https://USER:PASS@neocities.org/api/list?path=images"
{
  "result": "success",
  "files": [
    {
      "path": "images/cat.png",
      "is_directory": false,
      "size": 16793,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "41fe08fc0dd44e79f799d03ece903e62be25dc7d"
    }
  ]
}
</code></pre>

  <h2>GET /api/info</h2>
  <p>
    This call lets you retreive information about a web site. This call does not require site authorization if you provide a <strong>sitename</strong> argument. Note that the sitename is the same as a username. If you provide auth credentials, you will receive the info for the auth user's site. Dates conform to <strong>RFC2822</strong> format, and there are helpers for parsing it into a time object for most programming languages.
  </p>
  <h3>Examples</h3>
  <h6>Using cURL</h6>
  <pre><code class="bash">$ curl "https://neocities.org/api/info?sitename=youpi"
{
  "result": "success",
  "info": {
    "sitename": "youpi",
    "hits": 5072,
    "created_at": "Sat, 29 Jun 2013 10:11:38 +0000",
    "last_updated": "Tue, 23 Jul 2013 20:04:03 +0000",
    "domain": null,
    "tags": []
  }
}</code></pre>
  <p>Getting your own site's info:</p>
  <pre><code class="bash">$ curl "https://YOURUSER:YOURPASS@neocities.org/api/info"</code></pre>
  <h6>Using Node.js</h6>
  <p>Your site:</p>
  <pre><code class="javascript">var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.info(function(resp) {
  console.log(resp)
})</code></pre>

  <p>
    Getting data for a different site - such as the <a href="http://madamfrp.neocities.org" target="_blank">Madam FRP Manual</a>:
  </p>
  <pre><code class="javascript">var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.info('madamfrp', function(resp) {
  console.log(resp)
})</code></pre>



<h2>GET /api/key</h2>
<p>
  Returns an API key that you can use for the API instead of login credentials.
  It will automatically generate a new API key if one doesn't exist yet for your site.
</p>
<h3>Examples</h3>
<h6>Using cURL</h6>
<pre><code class="bash">$ curl "https://USER:PASS@neocities.org/api/key"
{
  "result": "success",
  "api_key": "da77c3530c30593663bf7b797323e48c"
}</code></pre>

  <p>Using the api key for requests:</p>

  <pre><code class="bash">$ curl -H "Authorization: Bearer da77c3530c30593663bf7b797323e48c" \
https://neocities.org/api/info</code></pre>

  <h2>Need something the API doesn't provide?</h2>
  <p>
    If the API does not supply something you need, <a href="/contact">contact us</a> and we will try to add it!
  </p>
</div>