Free file sharing
Welcome to 4shared REST API documentation!

Introduction

The 4shared API is built to conform to the design principles of Representational State Transfer (REST). 4shared resources like files, folders and users can be accessed and updated using the HTTP methods GET, POST, PUT and DELETE.

In general, a list of the resources is available through /{resource name}, to get a specific resource, use /{resource name}/{id} and subresources like a list of user's files can be received through /{resource name}/{id}/{subresource name}

The current API version is 0. Version is specified in the API URL: http://api.4shared.com/v0/



Public calls

You can start using the API after creating an application. Public API calls may be done with application's consumer key. This example shows how to get latest files:

http://api.4shared.com/v0/files.json?oauth_consumer_key={application's consumer key}
    In this example:
  • The format is specified by appending .json. If you do not append the format, it will be specified by the HTTP Accept header value or XML by default. However we strongly encourage you to use JSON and all examples will be provided using JSON.
  • The first parameter oauth_consumer_key={application's consumer key} needs to be replaced by your application's consumer key and used to authenticate as an application. To do requests on behalf of the 4shared user pass oauth_token instead of the oauth_consumer_key.
  • The response is an array of the files object. Each file has an attributes like name, type, size, etc.


Formats

4shared API supports xml, json and jsonp formats. The requested format can be specified by appending .format to the resource path:

http://api.4shared.com/v0/files.json?oauth_consumer_key={application's consumer key}

http://api.4shared.com/v0/files.xml?oauth_consumer_key={application's consumer key}

http://api.4shared.com/v0/files.jsonp?oauth_consumer_key={application's consumer key}

The alternative way of specifying format is setting the HTTP Accept header:

$ curl -H "Accept: application/json" "http://api.4shared.com/v0/files?oauth_consumer_key={application's consumer key}"

$ curl -H "Accept: application/xml" "http://api.4shared.com/v0/files?oauth_consumer_key={application's consumer key}"

$ curl -H "Accept: application/javascript" "http://api.4shared.com/v0/files?oauth_consumer_key={application's consumer key}"

If you're using JSONP, you need to pass a callback parameter:



Global request parameters

oauth_consumer_key is used to do public API calls.
oauth_token is used do API calls on the behalf of a 4shared user .
callback If callback is set and jsonp format format is requested, the API output will be wrapped in a call to the Javascript function named by the passed value. This function name may only contain alphanumeric characters and underscores.



Pagination

The default number of items you can receive is 100. This value can be changed by passing limit parameter; you can also change the starting item by passing offset parameter.

$ curl "http://api.4shared.com/v0/files?oauth_consumer_key={application consumer key}&offset=0&limit=20"

$ curl "http://api.4shared.com/v0/files?oauth_consumer_key={application consumer key}&offset=20&limit=20"


Filtering

You can search file lists by using keyword filtering. For example to find files that are relevant to the keyword "sky":

$ curl "http://api.4shared.com/v0/files.json?oauth_consumer_key={application's consumer key}&query=sky"

You can also filter file lists by categories. For example to find only video files:

$ curl "http://api.4shared.com/v0/files.json?oauth_consumer_key={application's consumer key}&category=2"

Categories:

  • 1 - Music
  • 2 - Video
  • 3 - Photo
  • 4 - Archieves
  • 5 - Books/Office
  • 6 - Programs
  • 7 - Web
  • 8 - Mobile
  • 9 - Games
  • 10 - Android

Authentication

To do public calls you need only application's consumer key, but to access resources on behalf of the 4shared user, your application should be granted access. 4shared uses OAuth 1.0 to authenticate API requests. See OAuth specification for details on authentication process.


Endpoints
Request token http://api.4shared.com/v0/oauth/initiate
Authorize token http://api.4shared.com/v0/oauth/authorize
Access token http://api.4shared.com/v0/oauth/token


Error Handling

Errors are returned using HTTP status code. Additional information may be included in the body of the result. For example:

$ curl -i http://api.4shared.com/v0/user.json HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, PUT, POST, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type, Accept
Content-Length: 30
{"ok":false,"message":"Bad or expired token","statusCode":401}


Common errors are:

400 Bad input parameter. Error message should indicate which one and why.
401 Bad or expired token. This can happen if the user or 4shared revoked or expired an access token. To fix, you should re-authenticate the user.
403 Resource is forbidden.
404 Resource not found at the specified path.
405 Request method not expected (generally should be GET or POST).
503 Your app is making too many requests and is being rate limited. 503s can trigger on a per-app or per-user basis.
507 User is over 4shared storage quota.