|
|
| Members: 203 |
| Language: English |
|
Group categories:
|
| More group info » |
File Upload Raw HTTP
| Oct 7 |
|
Full API Documentation
| Sep 8 |
|
Resource Descriptions
| Jul 24 |
|
Changelog
| Jun 18 |
|
HOW-TO use your own Authenication with the API
| Jun 15 |
|
Quick Start Guide
| Jun 15 |
|
Rate Limits
| Jun 15 |
IntroductionThis documentation will provide you with an overview of the RESTful style API that Drop.io has released to the public. Included in this documentation are access to the resources and services that we provide on our normal website. Sift through the documentation and let us know if there's any other information that you could need.
What is Drop.io?Drop.io is the simplest place to share files online. Privately share what you want, how you want, with who you want... Our main goal is to provide the most streamline, stress free ways to push digital content around on the web. There are no accounts and files are easily converted (if we can) to a web friendly format, so no extra software to install and convenient access to files any time you want. For more information, check out our About page. SummaryOur API aims to be incredibly simple and private, just like our website. In order for that to happen, we have taken the RESTful style approach to access our resources. Each drop and asset has a unique URL associated to it in which you can receive the content in XML or JSON format. For privacy and security purposes, each request will have an API key sent in as a parameter (described below) and for drops that have authentication mechanisms (both guest and admin), tokens or passwords should be sent in (described below as well). Each request will need to be URL encoded and we accept UTF-8 encodings only. API AccountsIn order to access our API, you will need to signup for a new Drop.io API account. This will give you an API key that you'll use with every request to the Drop.io API. It is very important to sign up for an API account as each request will be rejected unless you supply an API key parameter (described below).
You can request a new API account here: http://api.drop.io/api_accounts Rate LimitsAt launch, API accounts will be restricted to a maximum number of requests per minute. Currently the limit is projected to be 250 requests every 15 minutes, however this is not finalized yet. Api account holders who have larger production needs should contact us to have their rate limit increased. Our aim is for each brand new API account to be able to accommodate up to 10,000 users per day with a reasonable use pattern without contacting drop.io for an increase.
NB: The drop.io API rate limiting policy is being revised. You may experience lower throughput than described here while we are in pre-launch state. Please check back to this section at launch time for the final word. Authentication & AuthorizationThere are two mechanisms that work together to ensure that a request that is made from a 3rd party application to Drop.io actually comes from a user. Each drop has two means of identification: a password and a token. Whether the user is a normal authenticated guest or an admin, these tokens can be used to authenticate the person through the API.
API Key - An API Key (discussed above) will be required for every request and allows Drop.io to determine if the application is a legitimate application. If we find that an application is abusing user data or compromising the security of Drop.io users, we can shut off their access to the site and every 3rd party application related to the suspect API key will then be disabled; thus protecting user data.
Authorization Token - When a Drop has been created from the API with an admin and guest password, a guest_token and admin_token will be returned with the Drop resource (described below) that will have to be used with requests for those resources. The guest or admin password can also be sent in with each request, posing as the authorization token. Using the tokens allows 3rd party applications to authenticate a user without requiring the user to enter in a password into the application, in which it could be saved, copied, or stored without the guest's knowledge. The token will also be available on the drop through http://drop.io for drops created outside of the API. The user would then enter that into the 3rd party application. In a situation where the user does not have access to the token to enter it into the 3rd party application, the user's password can be used. This is the least favorite method and should be avoided. API RequestsWith access to resources in a RESTful manor, API requests are quite simple. Each resource will have a URL in which you can GET, POST, PUT, and DELETE to describing each action. And required parameters will be described below.
All API requests will go to http://api.drop.io/ Response FormatsRequests can include a format parameter (or a format extension .xml or .json) for each request. In return, you will get the error message or resource formatted as requested. Currently we support XML and JSON. RSS is included on the drop.io website.
Examples: http://api.drop.io/drops/example_drop/assets.xml http://api.drop.io/drops/example_drop/assets.json http://api.drop.io/drops/example_drop/assets?format=xml
You can see example resource responses in this document. Specifying API VersionRequests can include a version parameter to provide backwards compatibility when new versions of the API are released in the future. The launch version of the api will have version = 1.0. This parameter will become required soon; existing clients should be modified to include it.
Example: http://api.drop.io/drop/example_drop/assets?version=1.0
HTTP Status CodesHTTP Status codes are used to signal the state of a request made to the API. Here's a short list of common HTTP Codes used and what they mean:
Error MessagesFor 400 and 500 level HTTP Status Codes, we'll return a formatted error message containing a user friendly report of what happened. The formats are listed below of example error messages.
In XML:
<?xml version="1.0" encoding="UTF-8"?>
In JSON:
{"response":{"action":"show","message":"The api_key is invalid.","result":"Failure"}} ResourcesDrops and files are all accessible via RESTful URLs and meaningful HTTP Request methods. Below are descriptions of available resources (with URLs) and required HTTP methods. Required parameters are in bold and descriptions of returned values are included.
Resource locations (URLs) will have identifying information in their URL. In the descriptions below, the URL references starting with a colon like :drop_name, :asset_name, :comment_id, are values that are well known and returned with each Resource. You should replace these URL references with their real values.
Also don't forget about the formatting of resources (described above). You can add a format parameter or tag a (.xml or .json) to the end of each URL to get a formatted response. Drop ResourceCreate a drop When creating a drop, every parameter (aside from API key) is optional. You will get back a default drop with a random name and default settings (unless you provide the optional parameters). In response, you will get the guest and admin tokens that act as authorization tokens for authentication. URL: http://api.drop.io/drops Method: POST Parameters:
Get a drop When getting a drop, you will be returned a simplified version of the Drop in the format of your choice. Depending on the token provided and drop permissions, you may or may not receive certain details. For example, Drops that are created with a View Only setting, you will not receive the voicemail, fax, or email address values as they only pertain to users adding files. URL: http://api.drop.io/drops/:drop_name Method: GET Parameters:
Redirect to drop.io If there's a need to authenticate a web session on drop.io, example: when forwarding a person from your 3rd party system to Drop.io, this method will cause a session to be started and authentication to take place behind the scenes, relative to the signature in place. Depending on how the signature is constructed, the drop will log in appropriately for a guest or an admin. URL: http://drop.io/:drop_name/from_api Method: GET Parameters:
Update a drop When updating a drop, the parameters are optional and the token passed in for authentication must be the administrator token or password. URL: http://api.drop.io/drops/:drop_name Method: PUT Parameters:
Delete a drop When deleting a drop, you must supply the administrator token or password. URL: http://api.drop.io/drops/:drop_name Method: DELETE Parameters:
Asset ResourceCreating Assets Creating assets in Drop.io is as simplistic as we could make it. With Notes and Links being theoretically different entities, focusing on content rather than file contents, we have created two separate means for creating links, notes, and assets. The following descriptions will guide you in adding the meat and bones to your drop.
Create a Link When creating a link, the title and description are not necessary, but obviously the url is. URL: http://api.drop.io/drops/:drop_name/assets Method: POST Parameters:
Create a Note When creating a note, the title is optional, while the content is required. URL: http://api.drop.io/drops/:drop_name/assets Method: POST Parameters:
Create a File When uploading a file to Drop.io, you should post the file and the required parameters to the url in a multi-type encoded form. Uploading a file to a server via HTTP form post is described in RFC 1867: http://www.ietf.org/rfc/rfc1867.txt NOTE: The url for uploading is outside of the api.drop.io domain. When following the RF 1867, the Content-Disposition must include the name=file and filename=your_file_name. The Content-Type header may be omitted. An example of such a request that is accepted by Drop.io is here: http://groups.google.com/group/dropio-api/web/file-upload-raw-http. URL: http://assets.drop.io/upload Method: POST Parameters:
Get a list of assets When getting a list of assets associated to a drop, they will be returned in an array format as a list of assets ordered by their creation date. Note: Assets are returned in pages of 30 assets at a time. URL: http://api.drop.io/drops/:drop_name/assets Method: GET Parameters:
Get an asset When getting an asset, you will not receive the path to the direct original file download. Our business model requires a user to be authenticated and on our site to do that. Method: GET Parameters:
Get an asset embed code You can grab the assets embed code, for displaying a player or web representation of a file. You'll get a branded flash player back for videos, audio, and documents. For images and notes, you'll get a special div that contains links back to drop.io and a thumbnail of the content. Note: For json, you'll get an escaped embed code within a JSON asset array. For xml, you'll get an asset object with an embed_code node containing the html URL: http://api.drop.io/drops/:drop_name/assets/:asset_name/embed_code Method: GET Parameters:
Redirect to drop.io If there's a need to authenticate a web session on drop.io, example: when forwarding a person from your 3rd party system to Drop.io, this method will cause a session to be started and authentication to take place behind the scenes, relative to the signature in place. Depending on how the signature is constructed, the drop will log in appropriately for a guest or an admin. URL: http://drop.io/:drop_name/asset/:asset_name/from_api Method: GET Parameters:
Update an asset When updating an asset, you must have permissions to add or remove an asset before being able to edit the asset. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name Method: PUT Parameters:
Delete an asset When deleting an asset, you must supply the administrator token or password. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name Method: DELETE Parameters:
Send an asset When sending an asset, you must provide proper pairs of information to send to. For example, when the medium is 'fax' you must provide a 'fax_number'. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name/send_to Method: POST Parameters:
Comment ResourceGet a list of comments When getting a list of comments associated to an asset, they will be returned in an array format as a list of assets ordered by their creation date. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name/comments Method: GET Parameters:
Create a comment When creating a comment, you must have permissions to create a comment or add a note. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name/comments Method: POST Parameters:
Get a comment When getting a comment, you must have permissions to view the drop. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name/comments/:comment_id Method: GET Parameters:
Update a comment When updating a comment, you must supply the administrator token or password. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name/comments/:comment_id Method: PUT Parameters:
Delete a comment When deleting a comment, you must supply the administrator token or password. URL: http://api.drop.io/drops/:drop_name/assets/:asset_name/comments/:comment_id Method: DELETE Parameters:
Getting HelpThere are several ways to get help with Drop.io and its API. For faster results, you can consult our Discussions area where people, including Drop.io developers hang out and can answer your questions. If something isn't working right, you can also get help with Drop.io services through our Help page, including our GetSatisfaction page. AuthorsThis document is being edited and maintained by Drop.io Platform Evangelist Jacob Good (jake@dropio.com).
|
| |||||||||||||||||
| Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy |
| ©2009 Google |
|
