File Lifecycle

Create a File

Create a new File.

An App.net File object can be created without setting the file content. This is called an “incomplete” file object. To create an incomplete file object, POST a JSON document that matches the File schema with an HTTP header of Content-Type: application/json. Currently, the only keys we use from your JSON will be kind, type, name, public and annotations. You can also send those keys as standard form data instead of as JSON. Once you have an incomplete file object, you can set the file content in a later request.

You can also create a complete File object with one request by including the file content with the File metadata. To create a complete file object, send a POST with an HTTP header of Content-Type: multipart/form-data. Our API expects one part of the request body to contain a Content-Disposition header with a value for filename and name="content". The data from this part will be used as the file’s content. If you wish to send your data as Base64 encoded instead of as a byte stream you must include a Content-Transfer-Encoding: base64 header. If there is a part with name="metadata" and Content-Type: application/json then we will parse that JSON as the file’s metadata. Otherwise, we will construct the metadata from the form-data sent in the request body. If you send extra parts with a value for filename, the name

When creating a complete file, this endpoint could return a 507 Insufficient Storage error if the user doesn’t have enough space for this file. For more information, see file storage limits.

This endpoint responds to general File parameters.

Endpoint

Method URL Token
POST https://alpha-api.app.net/stream/0/files User
Please see the File Authorization documentation for more information on User and File tokens.

Example

JSON Metadata 2

The most comprehensive way to to specify a file’s attributes are to upload json data that fits the File schema with the file itself.

to see more complete examples.

echo '{
  "type": "com.example.test",
  "annotations": [
    {
      "type": "com.example.annotation",
      "value": {
        "foo": "bar"
      }
    }
  ]
}' | \
    curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    -F "metadata=@-;type=application/json" -F "content=@filename.jpg" \
    "https://alpha-api.app.net/stream/0/files"
Form-data metadata

The metadata can also be submitted as normal post data. If you want to create annotations on the file, you must use the JSON metadata format to do so.

Here is some sample File upload code written in Python. You can also use the following curl command to upload a file:

to see more complete examples.

curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    -F "type=com.example.test" -F "content=@filename.jpg" "https://alpha-api.app.net/stream/0/files"
Custom derived files

If you’d like to upload custom derived files at the same time as the original file, you can include the derived files as extra parts:

to see more complete examples.

curl -X POST -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    -F "type=com.example.test" -F "content=@filename.jpg" -F "derived_key1=@derived_file1.png;type=image/png" \
    -F "derived_key2=@derived_file2.png;type=image/png" "https://alpha-api.app.net/stream/0/files"
{
  "data": {
    "complete": true,
    "created_at": "2013-01-28T18:31:18Z",
    "derived_files": {
      "image_thumb_200s": {
        "image_info": {
          "width": 200,
          "height": 200
        },
        "name": "filename_image_thumb_200s.png",
        "mime_type": "image/png",
        "sha1": "be91cb06d69df13bb103a359ce70cf9fba31234a",
        "size": 33803,
        "url": "https://example.com/thumbnail_200s.png",
        "url_expires": "2013-01-25T03:00:00Z"
      },
      "image_thumb_960r": {
        "image_info": {
          "width": 600,
          "height": 800
        },
        "name": "filename_image_thumb_960r.png",
        "mime_type": "image/png",
        "size": 140173,
        "sha1": "57004b55119002f551be5b9f2d5439dd4ad1234a",
        "url": "https://example.com/thumbnail_960r.png",
        "url_expires": "2013-01-25T03:00:00Z"
      }
    },
    "file_token": "auCj3h64JZrhQ9aJdmwre3KP-QL9UtWHYvt5tj_64rUJWemoIV2W8eTJv9NMaGpBFk-BbU_aWA26Q40w4jFhiPBpnIQ_lciLwfh6o8YIAQGEQziksUMxZo7gOHJ_-niw3l3MZCh7QRWzqNGpiVaUEptfKO0fETrZ8bJjDa61234a",
    "id": "1",
    "image_info": {
      "width": 600,
      "height": 800
    },
    "kind": "image",
    "mime_type": "image/png",
    "name": "filename.png",
    "sha1": "ef0ccae4d36d4083b53e121a6cf9cc9d7ac1234a",
    "size": 172393,
    "source": {
      "name": "Clientastic for iOS",
      "link": "http://app.net",
      "client_id": "98765zyxw"
    },
    "total_size": 346369,
    "type": "com.example.test",
    "url": "https://...",
    "url_expires": "2013-01-25T03:00:00Z",
    "user": "...user object..."
  },
  "meta": {
    "code": 200
  }
}

Update a File

Updates a specific File object. You can update a file by PUTing an object that matches the File schema with an HTTP header of Content-Type: application/json. The only keys that can be updated are annotations, name and public. Only the File owner can update a File.

This endpoint currently works identically for the PUT and PATCH HTTP methods.

This endpoint responds to general File parameters.

Endpoint

Method URL Token
PUT https://alpha-api.app.net/stream/0/files/{file_id} User
Please see the File Authorization documentation for more information on User and File tokens.

URL Parameters

Name Description
file_id The id of the File to update.

Example

to see more complete examples.

curl -X PUT -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    -H "Content-Type: application/json" -d "{
  \"name\": \"update_filename.jpg\"
}" \
    "https://alpha-api.app.net/stream/0/files/1"
{
  "data": {
    "complete": true,
    "created_at": "2013-01-28T18:31:18Z",
    "derived_files": {
      "image_thumb_200s": {
        "image_info": {
          "width": 200,
          "height": 200
        },
        "name": "filename_image_thumb_200s.png",
        "mime_type": "image/png",
        "sha1": "be91cb06d69df13bb103a359ce70cf9fba31234a",
        "size": 33803,
        "url": "https://example.com/thumbnail_200s.png",
        "url_expires": "2013-01-25T03:00:00Z"
      },
      "image_thumb_960r": {
        "image_info": {
          "width": 600,
          "height": 800
        },
        "name": "filename_image_thumb_960r.png",
        "mime_type": "image/png",
        "size": 140173,
        "sha1": "57004b55119002f551be5b9f2d5439dd4ad1234a",
        "url": "https://example.com/thumbnail_960r.png",
        "url_expires": "2013-01-25T03:00:00Z"
      }
    },
    "file_token": "auCj3h64JZrhQ9aJdmwre3KP-QL9UtWHYvt5tj_64rUJWemoIV2W8eTJv9NMaGpBFk-BbU_aWA26Q40w4jFhiPBpnIQ_lciLwfh6o8YIAQGEQziksUMxZo7gOHJ_-niw3l3MZCh7QRWzqNGpiVaUEptfKO0fETrZ8bJjDa61234a",
    "id": "1",
    "image_info": {
      "width": 600,
      "height": 800
    },
    "kind": "image",
    "mime_type": "image/png",
    "name": "update_filename.jpg",
    "sha1": "ef0ccae4d36d4083b53e121a6cf9cc9d7ac1234a",
    "size": 172393,
    "source": {
      "name": "Clientastic for iOS",
      "link": "http://app.net",
      "client_id": "98765zyxw"
    },
    "total_size": 346369,
    "type": "com.example.test",
    "url": "https://...",
    "url_expires": "2013-01-25T03:00:00Z",
    "user": "...user object..."
  },
  "meta": {
    "code": 200
  }
}

Delete a File

Delete a file. The current user must be the same user who created the File. It returns the deleted File on success. Since a File could be referenced by multiple resources we recommend that you don’t automatically delete files when you delete Posts. Deleting a file should be a more explicit action taken by the user.

Remember, access tokens can not be passed in a HTTP body for DELETE requests. Please refer to the authentication documentation.

This endpoint responds to general File parameters.

Endpoint

Method URL Token
DELETE https://alpha-api.app.net/stream/0/files/{file_id} User
Please see the File Authorization documentation for more information on User and File tokens.

URL Parameters

Name Description
file_id The id of the File to delete.

Example

to see more complete examples.

curl -X DELETE -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    "https://alpha-api.app.net/stream/0/files/1"
{
  "data": {
    "complete": true,
    "created_at": "2013-01-28T18:31:18Z",
    "derived_files": {
      "image_thumb_200s": {
        "image_info": {
          "width": 200,
          "height": 200
        },
        "name": "filename_image_thumb_200s.png",
        "mime_type": "image/png",
        "sha1": "be91cb06d69df13bb103a359ce70cf9fba31234a",
        "size": 33803,
        "url": "https://example.com/thumbnail_200s.png",
        "url_expires": "2013-01-25T03:00:00Z"
      },
      "image_thumb_960r": {
        "image_info": {
          "width": 600,
          "height": 800
        },
        "name": "filename_image_thumb_960r.png",
        "mime_type": "image/png",
        "size": 140173,
        "sha1": "57004b55119002f551be5b9f2d5439dd4ad1234a",
        "url": "https://example.com/thumbnail_960r.png",
        "url_expires": "2013-01-25T03:00:00Z"
      }
    },
    "file_token": "auCj3h64JZrhQ9aJdmwre3KP-QL9UtWHYvt5tj_64rUJWemoIV2W8eTJv9NMaGpBFk-BbU_aWA26Q40w4jFhiPBpnIQ_lciLwfh6o8YIAQGEQziksUMxZo7gOHJ_-niw3l3MZCh7QRWzqNGpiVaUEptfKO0fETrZ8bJjDa61234a",
    "id": "1",
    "image_info": {
      "width": 600,
      "height": 800
    },
    "kind": "image",
    "mime_type": "image/png",
    "name": "filename.png",
    "sha1": "ef0ccae4d36d4083b53e121a6cf9cc9d7ac1234a",
    "size": 172393,
    "source": {
      "name": "Clientastic for iOS",
      "link": "http://app.net",
      "client_id": "98765zyxw"
    },
    "total_size": 346369,
    "type": "com.example.test",
    "url": "https://...",
    "url_expires": "2013-01-25T03:00:00Z",
    "user": "...user object..."
  },
  "meta": {
    "code": 200
  }
}