Fileslap's API

Introduction

Fileslap's RESTful API allows you to create, delete, and access info for files. To use this (or any) REST API, your application will make an HTTP request and parse the response. By default, the response is JSON. Fileslap's API is based on regular old HTTP, so you can use pretty much any language that speaks HTTP to interact with it.

For many of our examples, we will be using cURL since it's a really easy way to send HTTP requests using the command line.

Authentication

Fileslap's API uses HTTP basic authentication, and any and all interactions with the API must include the user's Fileslap username and password (passed using HTTP basic authentication). We'll show you some examples in a bit.

Response Format

When using GET or POST (i.e., whenever data is requested [GET] or when a new file is created[POST]), you should get a response back in JSON assuming all went well. This response will be a collection of data about one or many files, and it will look like this:

  {
      "views": 5, 
      "url": "/7yd/filename", 
      "filename": "filename.txt", 
      "fileurl": "http://media.dropdo.com.s3.amazonaws.com/7yd/filename.txt",
      "posted": "2011-08-18 12:32:42", 
      "type": "markdown", 
      "id": 12345, 
      "contents": "IyMgQSBjb21tYW5kIGxpbmUgZmlsZSB1cGxvYWRlciBmb3IgRmlsZXNsY", 
      "size": 435
  }

Here's a rundown on information about each of the fields:

File Creation

Now let's get to the nitty gritty. So you want to upload a file, eh? Cool, all Fileslap needs is the file itself along with the user's login info.

File creation is done by POST'ing a file to http://fileslap.com/api/files/ along with the user's username and password through HTTP basic authentication. The file must be called "file" in the request, and it must have a valid extension and be under the maximum file size for that user's account, otherwise you'll get an error.

Here's an example using cURL. Say we need to upload the file "filename.txt" to Fileslap, our username is joeuser and our password is pass123. We can run:

  # upload filename.txt to joeuser's Fileslap account
  $ curl -u joeuser:pass123 -F "file=@filename.txt" http://fileslap.com/api/files/

And if all went well, we will get back a JSON response like the example in the "Response Format" section above. You could then (for example) parse this, grabbing the url and outputting it to the user or copying it to the user's clipboard if desired.

File Retrieval

Getting info about files is super simple. You can either grab all the files for the user, or you can grab info about one specific file.

If you want to get info about all of them, just shoot a GET request to http://fileslap.com/api/files/ and pass the user's login info using HTTP basic authentication. Here's an example of this using cURL.

  # grab info for all of the joeuser's files
  $ curl -u joeuser:pass123 http://fileslap.com/api/files/

This will give you some JSON with info about all of that users' files, and it'll look like this:

  [
      {
          "views": 6, 
          "url": "/7yd/filename1", 
          "filename": "filename1.txt", 
          "fileurl": "http://media.dropdo.com.s3.amazonaws.com/7yd/filename1.txt",
          "posted": "2011-08-18 12:32:42", 
          "type": "markdown", 
          "id": 12345, 
          "contents": "IyMgQSBjb21tYW5kIGxpbmUgZmlsZSB1cGxvYWRlciBmb3IgRmlsZXNsY", 
          "size": 335
      },
      {
          "views": 5, 
          "url": "/7yf/filename2", 
          "filename": "filename2.txt", 
          "fileurl": "http://media.dropdo.com.s3.amazonaws.com/7yd/filename2.txt",
          "posted": "2011-08-18 12:32:58", 
          "type": "markdown", 
          "id": 12346, 
          "contents": "IyMgQSBjb21tYW5kIGxpbmUgZmlsZSB1cGxvYWRlciBmb3IgRmlsZXNsY", 
          "size": 435
      }
  ]

For info about those fields, see the "Response Format" section above.

Now say that you only want to grab info about one file. To do this, you must know its ID (see the "id" field above), and you can just add it onto the end of the URL that you're GET'ting. Here's an example, using cURL:

  # grab info for one specific file belonging to joeuser (the one with the ID of 12345)
  $ curl -u joeuser:pass123 http://fileslap.com/api/files/12345/

That will send you some JSON back in the format above for the file with ID 12345.

File Deletion

File deletion just involves sending a DELETE request to http://fileslap.com/api/files/12345/ where 12345 is the file's ID.

For example, say that joeuser uploaded filename.txt by mistake and wants to delete it. He can first retrieve its ID by grabbing info about his files (see the "File Info Retrieval" section). Then, once he has its ID (let's say it's 5678), he can delete it by running a DELETE request to http://fileslap.com/api/files/5678/ and passing along his login info using HTTP basic authentication (as if you haven't heard that enough). Here's how that would look using cURL:

  # delete one specific file belonging to joeuser (the one with the ID of 5678)
  $ curl -u joeuser:pass123 http://fileslap.com/api/files/5678/

Unlike when creating a view and when grabbing a file's info, you don't get JSON back when deleting a file. In fact, you get nothing in the response body. If you're paranoid, you can check the status code of the response (it should be "204" if the object was successfully deleted) but that shouldn't be necessary because if there's an error, you'll see it.

Code Samples

Here are some different code samples taking you too a quick runthrough of everything we talked about above.