{"id":13878302,"url":"https://github.com/Jesus/dropbox_api","last_synced_at":"2025-07-16T14:31:55.469Z","repository":{"id":10165520,"uuid":"53198237","full_name":"Jesus/dropbox_api","owner":"Jesus","description":"Ruby client library for Dropbox API v2","archived":false,"fork":false,"pushed_at":"2024-06-25T01:34:09.000Z","size":2182,"stargazers_count":171,"open_issues_count":9,"forks_count":113,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-14T12:26:55.339Z","etag":null,"topics":["api-client","dropbox","dropbox-api"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jesus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-03-05T11:31:36.000Z","updated_at":"2024-09-23T10:18:50.000Z","dependencies_parsed_at":"2024-01-08T18:30:25.107Z","dependency_job_id":null,"html_url":"https://github.com/Jesus/dropbox_api","commit_stats":{"total_commits":377,"total_committers":32,"mean_commits":11.78125,"dds":"0.33156498673740054","last_synced_commit":"11bd1cf5f9a3683f1956857f9187b68134a7eddd"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jesus%2Fdropbox_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jesus%2Fdropbox_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jesus%2Fdropbox_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jesus%2Fdropbox_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jesus","download_url":"https://codeload.github.com/Jesus/dropbox_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226138849,"owners_count":17579496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","dropbox","dropbox-api"],"created_at":"2024-08-06T08:01:45.707Z","updated_at":"2024-11-24T07:30:57.047Z","avatar_url":"https://github.com/Jesus.png","language":"Ruby","readme":"# DropboxApi\n\nLibrary for communicating with Dropbox API v2.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'dropbox_api'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install dropbox_api\n\n## Documentation\n\nPlease, refer to this gem's custom [Dropbox API\ndocumentation](http://jesus.github.io/dropbox_api).\nMost of the time you'll be checking the [available\nendpoints](http://jesus.github.io/dropbox_api/DropboxApi/Client.html).\n\nUnfortunately, the documentation at [RubyDoc.info](http://www.rubydoc.info) is\ndisrecommended because it lacks some nice features that have been added with\nYARD plugins:\n\n- Each endpoint includes its tests right below the description, this works as\n  an example of its usage.\n- All endpoints are shown as methods of the `Client` class, just as you will\n  use them.\n\n## Basic set up\n\n### Authorize your application\n\nDropbox uses OAuth, in order to use this library from your application you'll\nhave to get an authorization code.\n\nOnce you have it, just pass it on client initialization:\n\n```ruby\nDropboxApi::Client.new(\"VofXAX8D...\")\n#=\u003e #\u003cDropboxApi::Client ...\u003e\n```\n\nOr set it as an ENV variable called `DROPBOX_OAUTH_BEARER`, for example:\n\n```ruby\nENV[\"DROPBOX_OAUTH_BEARER\"] = \"VofXAX8D...\"\nDropboxApi::Client.new\n#=\u003e #\u003cDropboxApi::Client ...\u003e\n```\n\nThe official documentation on the process to get an authorization code is\n[here](https://developers.dropbox.com/es-es/oauth-guide#implementing-oauth),\nit describes the two options listed below.\n\n\n#### Option A: Get your access token from the website\n\nFor a quick test, you can obtain an access token from the App Console in\n[Dropbox's website](https://www.dropbox.com/developers/). Select from\n*My apps* your application, you may need to create one if you\nhaven't done so yet. Under your application settings, find section\n*OAuth 2*, there is a button to generate an access token.\n\n#### Option B: OAuth2 Code Flow\n\nThis is typically what you will use in production, you can obtain an\nauthorization code with a 3-step process:\n\n```ruby\n# 1. Get an authorization URL.\nauthenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)\nauthenticator.auth_code.authorize_url #=\u003e \"https://www.dropbox.com/...\"\n\n# 2. Log into Dropbox and authorize your app. You need to open the\n# authorization URL in your browser.\n\n# 3. Exchange the authorization code for a reusable access token (not visible\n#    to the user).\naccess_token = authenticator.auth_code.get_token(CODE) #=\u003e #\u003cOAuth2::AccessToken ...\u003e`\naccess_token.token #=\u003e \"VofXAX8D...\"\n\n# Keep this token, you'll need it to initialize a `DropboxApi::Client` object:\nclient = DropboxApi::Client.new(access_token: access_token)\n\n# For backwards compatibility, the following also works:\nclient = DropboxApi::Client.new(access_token.token)\n```\n\n##### Integration with Rails\n\nIf you have a Rails application, you might be interested in this [setup\nguide](http://jesus.github.io/dropbox_api/file.rails_setup.html).\n\n\n##### Using refresh tokens\n\nAccess tokens are short-lived by default (as of September 30th, 2021),\napplications that require long-lived access to the API without additional\ninteraction with the user should use refresh tokens.\n\nThe process is similar but a token refresh might seamlessly occur as you\nperform API calls. When this happens you'll need to store the\nnew token hash if you want to continue using this session, you can use the\n`on_token_refreshed` callback to do this.\n\n```ruby\n# 1. Get an authorization URL, requesting offline access type.\nauthenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)\nauthenticator.auth_code.authorize_url(token_access_type: 'offline')\n\n# 2. Log into Dropbox and authorize your app. You need to open the\n#    authorization URL in your browser.\n\n# 3. Exchange the authorization code for a reusable access token\naccess_token = authenticator.auth_code.get_token(CODE) #=\u003e #\u003cOAuth2::AccessToken ...\u003e`\n\n# You can now use the access token to initialize a DropboxApi::Client, you\n# should also provide a callback function to store the updated access token\n# whenever it's refreshed.\nclient = DropboxApi::Client.new(\n  access_token: access_token,\n  on_token_refreshed: lambda { |new_token_hash|\n    # token_hash is a serializable Hash, something like this:\n    # {\n    #   \"uid\"=\u003e\"440\",\n    #   \"token_type\"=\u003e\"bearer\",\n    #   \"scope\"=\u003e\"account_info.read account_info.write...\",\n    #   \"account_id\"=\u003e\"dbid:AABOLtA1rT6rRK4vajKZ...\",\n    #   :access_token=\u003e\"sl.A5Ez_CBsqJILhDawHlmXSoZEhLZ4nuLFVRs6AJ...\",\n    #   :refresh_token=\u003e\"iMg4Me_oKYUAAAAAAAAAAapQixCgwfXOxuubCuK_...\",\n    #   :expires_at=\u003e1632948328\n    # }\n    SomewhereSafe.save(new_token_hash)\n  }\n)\n```\n\nOnce you've gone through the process above, you can skip the steps that require\nuser interaction in subsequent initializations of `DropboxApi::Client`. For\nexample:\n\n```ruby\n# 1. Initialize an authenticator\nauthenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)\n\n# 2. Retrieve the token hash you previously stored somewhere safe, you can use\n#    it to build a new access token.\naccess_token = OAuth2::AccessToken.from_hash(authenticator, token_hash)\n\n# 3. You now have an access token, so you can initialize a client like you\n#    would normally:\nclient = DropboxApi::Client.new(\n  access_token: access_token,\n  on_token_refreshed: lambda { |new_token_hash|\n    SomewhereSafe.save(new_token_hash)\n  }\n)\n```\n\n### Performing API calls\n\nOnce you've initialized a client, for example:\n\n```ruby\nclient = DropboxApi::Client.new(\"VofXAX8D...\")\n#=\u003e #\u003cDropboxApi::Client ...\u003e\n```\n\nYou can perform an API call like this:\n\n```ruby\nresult = client.list_folder \"/sample_folder\"\n#=\u003e #\u003cDropboxApi::Results::ListFolderResult\u003e\nresult.entries\n#=\u003e [#\u003cDropboxApi::Metadata::Folder\u003e, #\u003cDropboxApi::Metadata::File\u003e]\nresult.has_more?\n#=\u003e false\n```\n\nThe instance of `Client` we've initialized is the one you'll be using to\nperform API calls. You can check the class' documentation to find\n[all available endpoints](http://jesus.github.io/dropbox_api/DropboxApi/Client.html).\n\n### Large file uploads\n\nIf you need to upload files larger than 150MB the default `#upload` endpoint\nwon't work. Instead, you need to start a upload session and upload\nthe file in small chunks.\n\nTo make this easier, the method `upload_by_chunks` will handle this for you,\nexample:\n\n```ruby\nclient = DropboxApi::Client.new(\"VofXAX8D...\")\n#=\u003e #\u003cDropboxApi::Client ...\u003e\nFile.open(\"large_file.avi\") do |f|\n  client.upload_by_chunks \"/remote_path.txt\", f\nend\n```\n\nCheck out the\n[method documentation](http://www.xuuso.com/dropbox_api/DropboxApi/Client.html#upload_by_chunks-instance_method)\nto find out all available options.\n\n### Accessing Team Folders\n\nIn order to access your team scope you need to add the namespace_id to you request headers.\nThis can be done using the middlewere layer as per the below:\n\n```ruby\nclient = DropboxApi::Client.new(\"VofXAX8D...\")\n#=\u003e #\u003cDropboxApi::Client ...\u003e\nclient.namespace_id = client.get_current_account.root_info.root_namespace_id\n\nclient.list_folder('')\n#=\u003e Now returns the team folders\n```\n\nYou could unset the namespace ID at any point afterwards with just:\n\n```ruby\nclient.namespace_id = nil\n```\n\n## Dependencies\n\nThis gem depends on\n[oauth2](https://github.com/oauth-xx/oauth2)\nand\n[faraday](https://github.com/lostisland/faraday).\n\nIt has official support for Ruby versions `2.x`.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`bin/console` for an interactive prompt that will allow you to experiment.\n\n### Testing\n\nI recommend you to use a test account other than your main one.\n\nWe use VCR to record the HTTP calls to Dropbox, however we sometimes need to\nregenerate the cassettes. Let's take `list_folder` as an example to show what\nwould be the procedure to do so:\n\n 1. Manually delete the existing cassettes in\n    `spec/fixtures/vcr_cassettes/list_folder/*.yml`.\n\n 2. Run the task to build the scaffolding in your Dropbox account so the tests\n    will pass. If it doesn't exist you may need to write it yourself, check\n    the `DropboxScaffoldBuilder` class to find all existing scaffold builders.\n\n    ```text\n    DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER rake test:build_scaffold[list_folder]\n    ```\n\n    Note that you'll have to type `rake test:build_scaffold\\[list_folder\\]`\n    if you use `zsh`.\n\n    You can build all available scaffolds with just `rake test:build_scaffold`.\n\n 3. Run the tests and the cassettes will be written:\n\n    ```text\n    DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER rspec spec/endpoints/files/list_folder_spec.rb\n    ```\n\nThe OAuth bearer shouldn't have been recorded in the cassette and it should've\nbeen filtered. However, you may want to double check before pushing your\nupdates to Github.\n\nTip: you can simply run `export DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER` at\nthe beginning of your work session so you don't need to prefix it in every\ncommand line.\n\n## Contributing\n\nAny help will be much appreciated. The easiest way to help is to implement one\nor more of the [endpoints that are still pending](http://jesus.github.io/dropbox_api/file.api_coverage.html). To see how the\nendpoints are implemented, check out the `lib/dropbox_api/endpoints` folder.\n","funding_links":[],"categories":["Ruby","Third-party APIs"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJesus%2Fdropbox_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJesus%2Fdropbox_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJesus%2Fdropbox_api/lists"}