uploadcare-ruby 1.2.1 → 3.0.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (98) hide show
  1. checksums.yaml +5 -5
  2. data/.github/workflows/gem-push.yml +20 -0
  3. data/.github/workflows/ruby.yml +52 -0
  4. data/.gitignore +13 -5
  5. data/.rspec +3 -0
  6. data/.rubocop.yml +20 -0
  7. data/.yardopts +4 -0
  8. data/CHANGELOG.md +25 -24
  9. data/DEVELOPMENT.md +18 -0
  10. data/Gemfile +2 -0
  11. data/LICENSE +1 -1
  12. data/README.md +191 -519
  13. data/Rakefile +6 -4
  14. data/bin/console +15 -0
  15. data/bin/setup +8 -0
  16. data/lib/uploadcare.rb +36 -26
  17. data/lib/uploadcare/api/api.rb +25 -0
  18. data/lib/uploadcare/client/file_client.rb +44 -0
  19. data/lib/uploadcare/client/file_list_client.rb +46 -0
  20. data/lib/uploadcare/client/group_client.rb +45 -0
  21. data/lib/uploadcare/client/multipart_upload/chunks_client.rb +46 -0
  22. data/lib/uploadcare/client/multipart_upload_client.rb +62 -0
  23. data/lib/uploadcare/client/project_client.rb +18 -0
  24. data/lib/uploadcare/client/rest_client.rb +73 -0
  25. data/lib/uploadcare/client/rest_group_client.rb +23 -0
  26. data/lib/uploadcare/client/upload_client.rb +35 -0
  27. data/lib/uploadcare/client/uploader_client.rb +93 -0
  28. data/lib/uploadcare/client/webhook_client.rb +43 -0
  29. data/lib/uploadcare/concern/error_handler.rb +54 -0
  30. data/lib/uploadcare/concern/throttle_handler.rb +25 -0
  31. data/lib/uploadcare/concern/upload_error_handler.rb +32 -0
  32. data/lib/uploadcare/entity/decorator/paginator.rb +81 -0
  33. data/lib/uploadcare/entity/entity.rb +18 -0
  34. data/lib/uploadcare/entity/file.rb +81 -0
  35. data/lib/uploadcare/entity/file_list.rb +30 -0
  36. data/lib/uploadcare/entity/group.rb +41 -0
  37. data/lib/uploadcare/entity/group_list.rb +24 -0
  38. data/lib/uploadcare/entity/project.rb +13 -0
  39. data/lib/uploadcare/entity/uploader.rb +73 -0
  40. data/lib/uploadcare/entity/webhook.rb +14 -0
  41. data/lib/uploadcare/exception/request_error.rb +9 -0
  42. data/lib/uploadcare/exception/throttle_error.rb +14 -0
  43. data/lib/uploadcare/param/authentication_header.rb +25 -0
  44. data/lib/uploadcare/param/param.rb +10 -0
  45. data/lib/uploadcare/param/secure_auth_header.rb +37 -0
  46. data/lib/uploadcare/param/simple_auth_header.rb +14 -0
  47. data/lib/uploadcare/param/upload/signature_generator.rb +24 -0
  48. data/lib/uploadcare/param/upload/upload_params_generator.rb +23 -0
  49. data/lib/uploadcare/param/user_agent.rb +21 -0
  50. data/lib/uploadcare/ruby/version.rb +5 -0
  51. data/uploadcare-ruby.gemspec +50 -36
  52. metadata +112 -96
  53. data/.travis.yml +0 -12
  54. data/lib/uploadcare/api.rb +0 -24
  55. data/lib/uploadcare/api/file_api.rb +0 -7
  56. data/lib/uploadcare/api/file_list_api.rb +0 -8
  57. data/lib/uploadcare/api/group_api.rb +0 -38
  58. data/lib/uploadcare/api/group_list_api.rb +0 -8
  59. data/lib/uploadcare/api/project_api.rb +0 -9
  60. data/lib/uploadcare/api/raw_api.rb +0 -44
  61. data/lib/uploadcare/api/uploading_api.rb +0 -110
  62. data/lib/uploadcare/errors/errors.rb +0 -64
  63. data/lib/uploadcare/resources/file.rb +0 -164
  64. data/lib/uploadcare/resources/file_list.rb +0 -41
  65. data/lib/uploadcare/resources/group.rb +0 -115
  66. data/lib/uploadcare/resources/group_list.rb +0 -31
  67. data/lib/uploadcare/resources/project.rb +0 -13
  68. data/lib/uploadcare/rest/auth/auth.rb +0 -31
  69. data/lib/uploadcare/rest/auth/secure.rb +0 -43
  70. data/lib/uploadcare/rest/auth/simple.rb +0 -16
  71. data/lib/uploadcare/rest/connections/api_connection.rb +0 -32
  72. data/lib/uploadcare/rest/connections/upload_connection.rb +0 -21
  73. data/lib/uploadcare/rest/middlewares/auth_middleware.rb +0 -24
  74. data/lib/uploadcare/rest/middlewares/parse_json_middleware.rb +0 -33
  75. data/lib/uploadcare/rest/middlewares/raise_error_middleware.rb +0 -21
  76. data/lib/uploadcare/utils/parser.rb +0 -71
  77. data/lib/uploadcare/utils/user_agent.rb +0 -44
  78. data/lib/uploadcare/version.rb +0 -3
  79. data/spec/api/raw_api_spec.rb +0 -25
  80. data/spec/resources/file_list_spec.rb +0 -64
  81. data/spec/resources/file_spec.rb +0 -222
  82. data/spec/resources/group_list_spec.rb +0 -30
  83. data/spec/resources/group_spec.rb +0 -101
  84. data/spec/resources/operations_spec.rb +0 -59
  85. data/spec/resources/project_spec.rb +0 -21
  86. data/spec/rest/api_connection_spec.rb +0 -68
  87. data/spec/rest/auth/secure_spec.rb +0 -66
  88. data/spec/rest/auth/simple_spec.rb +0 -31
  89. data/spec/rest/errors_spec.rb +0 -75
  90. data/spec/rest/upload_connection_spec.rb +0 -19
  91. data/spec/spec_helper.rb +0 -41
  92. data/spec/uploadcare_spec.rb +0 -16
  93. data/spec/uploading/uploading_multiple_spec.rb +0 -43
  94. data/spec/uploading/uploading_spec.rb +0 -40
  95. data/spec/utils/parser_spec.rb +0 -87
  96. data/spec/utils/user_agent_spec.rb +0 -46
  97. data/spec/view.png +0 -0
  98. data/spec/view2.jpg +0 -0
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: ad96fa0d1ad6cea7d89b3b1bab8c78b9cf065491
4
- data.tar.gz: 34783372b519d4b381b915ddcfe95a0e379d69ab
2
+ SHA256:
3
+ metadata.gz: 4bdafd33b7c8ae9c4497155542a87b3b1797d72828d9be8649c74b731afefe10
4
+ data.tar.gz: e88de8ba3a43eb0ed7fa878d34831a11dadd7e1d103ea9781beed93bcd9b5eb9
5
5
  SHA512:
6
- metadata.gz: 9336a0ae85297a8e41ad81de42438f4590bb5a08aa0fb1766cbc2d48a09df260a2f38f63174b7549f9fad00961306bf38fa29fb69503fe75d79a394f1ef3520b
7
- data.tar.gz: 7d1caa97fdd3126394ddfa57dfed635ecd4b7c564331e5e92b072b8425d72a4f4a40a1ab2c592e00fd733aa7430733fd0e3d973fb3b404866e11da0d448b65c3
6
+ metadata.gz: f7adc9b72cf7587f09d6ffc1f3eea789d3c2c7ccb747b364b254a89783449aac38185a0cfcde5c7c89088eee658629804d606a1111d213e97433bc4727b31f2b
7
+ data.tar.gz: e88dc8694ac67b3eefba88218b111a5d51f8696e3dc9de9d3f46cf3bd7dbfadc53589ce2f94e43b78d1279758821edbe206c24a62df4088d126f76b90f200d94
@@ -0,0 +1,20 @@
1
+ name: Publish Gem
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - v*
7
+ jobs:
8
+ build:
9
+ runs-on: ubuntu-latest
10
+
11
+ steps:
12
+ - uses: actions/checkout@v1
13
+
14
+ - name: Release Gem
15
+ if: contains(github.ref, 'refs/tags/v')
16
+ uses: cadwallion/publish-rubygems-action@v1.0.0
17
+ env:
18
+ GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
19
+ RUBYGEMS_API_KEY: ${{secrets.RUBYGEMS_API_KEY}}
20
+ RELEASE_COMMAND: rake release
@@ -0,0 +1,52 @@
1
+ # This workflow uses actions that are not certified by GitHub.
2
+ # They are provided by a third-party and are governed by
3
+ # separate terms of service, privacy policy, and support
4
+ # documentation.
5
+ # This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
6
+ # For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
7
+
8
+ name: Ruby
9
+
10
+ on: [push, pull_request]
11
+
12
+ jobs:
13
+ test:
14
+
15
+ runs-on: ubuntu-latest
16
+ strategy:
17
+ matrix:
18
+ ruby-version: [
19
+ '2.4', '2.5', # eol
20
+ '2.6', '2.7', # maintained
21
+ ]
22
+
23
+ steps:
24
+ - uses: actions/checkout@v2
25
+ - name: Set up Ruby
26
+ uses: ruby/setup-ruby@v1
27
+ with:
28
+ ruby-version: ${{ matrix.ruby-version }}
29
+ bundler-cache: true
30
+ - name: Run tests
31
+ run: bundle exec rake
32
+ env:
33
+ UPLOADCARE_PUBLIC_KEY: demopublickey
34
+ UPLOADCARE_SECRET_KEY: demoprivatekey
35
+
36
+ style-check:
37
+ runs-on: ubuntu-latest
38
+ continue-on-error: true
39
+ strategy:
40
+ matrix:
41
+ ruby-version: ['2.7',]
42
+ steps:
43
+ - uses: actions/checkout@v2
44
+ - name: Set up Ruby
45
+ uses: ruby/setup-ruby@v1
46
+ with:
47
+ ruby-version: ${{ matrix.ruby-version }}
48
+ bundler-cache: true
49
+ - name: Install Rubocop
50
+ run: gem install rubocop
51
+ - name: Check codestyle
52
+ run: rubocop
data/.gitignore CHANGED
@@ -1,6 +1,14 @@
1
- Gemfile.lock
2
- .ruby-gemset
3
- .ruby-version
1
+ /.bundle/
2
+ /.yardoc
3
+ /_yardoc/
4
+ /coverage/
5
+ /doc/
6
+ /pkg/
7
+ /spec/reports/
8
+ /tmp/
9
+ /spec/fixtures/big.jpeg
4
10
 
5
- *.DS_Store
6
- *.gem
11
+ # rspec failure tracking
12
+ .rspec_status
13
+ .byebug_history
14
+ Gemfile.lock
data/.rspec ADDED
@@ -0,0 +1,3 @@
1
+ --format documentation
2
+ --color
3
+ --require spec_helper
data/.rubocop.yml ADDED
@@ -0,0 +1,20 @@
1
+ AllCops:
2
+ TargetRubyVersion: 2.7
3
+
4
+ Metrics/LineLength:
5
+ Max: 120
6
+
7
+ IneffectiveAccessModifier:
8
+ Enabled: false
9
+
10
+ Metrics/BlockLength:
11
+ Exclude:
12
+ - 'bin/'
13
+ - 'spec/**/*'
14
+ - 'uploadcare-ruby.gemspec'
15
+
16
+ Metrics/MethodLength:
17
+ Max: 20
18
+
19
+ Style/Documentation:
20
+ Enabled: false
data/.yardopts ADDED
@@ -0,0 +1,4 @@
1
+ -
2
+ DEVELOPMENT.md
3
+ CHANGELOG.md
4
+ LICENSE
data/CHANGELOG.md CHANGED
@@ -1,37 +1,38 @@
1
1
  # Changelog
2
- All notable changes to this project will be documented in this file.
3
2
 
4
- The format is based now on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
5
- and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
3
+ ## [Unreleased](https://github.com/uploadcare/uploadcare-ruby/tree/develop)
6
4
 
5
+ [Full Changelog](https://github.com/uploadcare/uploadcare-ruby/compare/0baded5593869f1d741f0fff22c58814970726b2...HEAD)
7
6
 
8
- ### [1.2.1] - 2018-05-24
9
-
10
- ### Changed
11
- - Allow user to override User-Agent header
12
- - User-Agent format reports gem name, version and environment
7
+ ## [3.0.4-dev] 2020-03-19
13
8
 
9
+ - Added better pagination methods for GroupList & FileList
10
+ - Improved documentation and install instructions
11
+ - Added CI
14
12
 
15
- ## 1.1.0 - 2017-03-21
16
-
17
- ### Added
18
- - Added to new methods to `Uploadcare::Api::File`, `#internal_copy` and `#external_copy`.
19
- - Added support of [secure authorization](https://uploadcare.com/documentation/rest/#request) for REST API. It is now used by default (can be overriden in config)
13
+ ## [3.0.3-dev] 2020-03-13
14
+ - Added better pagination and iterators for GroupList & FileList
20
15
 
21
- ### Fixed
22
- - Fixed middleware names that could break other gems ([#13](https://github.com/uploadcare/uploadcare-ruby/issues/13)).
16
+ ## [3.0.2-dev] 2020-03-11
23
17
 
24
- ### Deprecated
25
- - `Uploadcare::Api::File#copy` in favor of `#internal_copy` and `#external_copy`.
18
+ - Expanded File and Group entities
19
+ - Changed user agent syntax
26
20
 
21
+ ## [3.0.1-dev] 2020-03-11
27
22
 
28
- ## 1.0.6 - 2017-01-30
23
+ - Added Upload/group functionality
24
+ - Added user API
25
+ - Added user agent
26
+ - Isolated clients, entities and concerns
27
+ - Expanded documentation
28
+ ## [3.0.0-dev] 2020-02-18
29
+ ### Changed
30
+ - Rewrote gem from scratch
29
31
 
30
32
  ### Added
31
- - Ruby version and public API key sent via User-Agent header (can be overriden in config)
32
-
33
- ### Fixed
34
- - Incorrect dependencies
35
-
36
33
 
37
- [1.2.1]: https://github.com/uploadcare/uploadcare-ruby/compare/6dde...v1.2.1
34
+ - Client wrappers for REST API
35
+ - Serializers for REST API
36
+ - Client wrappers for Upload API
37
+ - Serializers for Upload API
38
+ - rdoc documentation
data/DEVELOPMENT.md ADDED
@@ -0,0 +1,18 @@
1
+ ## How to contribute
2
+
3
+ https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md
4
+
5
+ ## Useful docs
6
+
7
+ ### Uploadcare:
8
+
9
+ * https://uploadcare.com/docs/api_reference/
10
+ * https://uploadcare.com/api-refs/rest-api/
11
+
12
+ ### ApiStruct:
13
+
14
+ * https://github.com/rubygarage/api_struct/
15
+
16
+ ## Uploadcare-ruby gem architecture
17
+
18
+ ![http://www.plantuml.com/plantuml/uml/bPHDRzj838Rl-XM4zn1WiHRsOoyR88iuXOFcKWHDqcimaLxBquvcL9AowtxyzqepqYGrYY050cH69X-IByav5pMiVUkAed96X5QTfIy54T7jrWgDVrx16rE1De6fGKkzW2NQB9VB-7_zoRIT0zLmQ8oYfXQw3RMS9ZFgEnTCFLqsrk7UMT7YsnnsxTNguIZoNNIg38DMrrU4P2DWQvpz32wZzPtqnha3MStXXH9rIe8qq2jduPMSEO3_Y7x6rzJ0WwD3fjOK7jwZKg4DXvOOqWKlIB6klAZn5JBPS3v7UOQJ83j9-RnAASsNQHNlPsTdFv3iKJu9yJjT1gPBwp0ZHGCZdMDqHPP-LkPH-YGIjSQR1aACZpr4HnMFElApudwryMyXeUSAzDl5nSMGn0XIUB71HqLJrosacAj_4vHwGKtMqp_bd-LVongxH-0DU6ShJFMyCsn3BxI5wy1JQnDudS77LMJTfdfNjUaKFDnrb4Uc23KgMsDWXprfI7lICPHEKj4d4PBqe0SpfXmyTHnsjivZTZBDQlca8S5NO2zJ2Mlcm5GPhRPWYMEB-6ax71tusG8MY-Xu7praiI0sLY13dpceEYHuDBQRk6KCxTbBdc7QMzrI5MhGlt__bx4f-BqcZlNDm5Rp0K9cAZbcgcmH9uTxJrR9DCRw56-_XSSEF7vke4SvFSfnRTYqUJmXo5qqd5VDFhZfVKeRFIH4kwdthszlhwaRAL6gED2MCVJay8A1pfDyOnjlj6VCCGBBcEMgiuFFr__dD-mqx_VJ1sZ-DTPKf4joc_RlzBdNosC_sHLvOSe9ESFAUVIBYLWcwOeyJ-NCE8Ul-zPz1m00](http://www.plantuml.com/plantuml/svg/bPHDRzj838Rl-XM4zn1WiHRsOoyR88iuXOFcKWHDqcimaLxBquvcL9AowtxyzqepqYGrYY050cH69X-IByav5pMiVUkAed96X5QTfIy54T7jrWgDVrx16rE1De6fGKkzW2NQB9VB-7_zoRIT0zLmQ8oYfXQw3RMS9ZFgEnTCFLqsrk7UMT7YsnnsxTNguIZoNNIg38DMrrU4P2DWQvpz32wZzPtqnha3MStXXH9rIe8qq2jduPMSEO3_Y7x6rzJ0WwD3fjOK7jwZKg4DXvOOqWKlIB6klAZn5JBPS3v7UOQJ83j9-RnAASsNQHNlPsTdFv3iKJu9yJjT1gPBwp0ZHGCZdMDqHPP-LkPH-YGIjSQR1aACZpr4HnMFElApudwryMyXeUSAzDl5nSMGn0XIUB71HqLJrosacAj_4vHwGKtMqp_bd-LVongxH-0DU6ShJFMyCsn3BxI5wy1JQnDudS77LMJTfdfNjUaKFDnrb4Uc23KgMsDWXprfI7lICPHEKj4d4PBqe0SpfXmyTHnsjivZTZBDQlca8S5NO2zJ2Mlcm5GPhRPWYMEB-6ax71tusG8MY-Xu7praiI0sLY13dpceEYHuDBQRk6KCxTbBdc7QMzrI5MhGlt__bx4f-BqcZlNDm5Rp0K9cAZbcgcmH9uTxJrR9DCRw56-_XSSEF7vke4SvFSfnRTYqUJmXo5qqd5VDFhZfVKeRFIH4kwdthszlhwaRAL6gED2MCVJay8A1pfDyOnjlj6VCCGBBcEMgiuFFr__dD-mqx_VJ1sZ-DTPKf4joc_RlzBdNosC_sHLvOSe9ESFAUVIBYLWcwOeyJ-NCE8Ul-zPz1m00)
data/Gemfile CHANGED
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  source 'https://rubygems.org'
2
4
 
3
5
  # Specify your gem's dependencies in uploadcare-ruby.gemspec
data/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  The MIT License (MIT)
2
2
 
3
- Copyright (c) 2017 Uploadcare, LLC
3
+ Copyright (c) 2021 Uploadcare Inc.
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
data/README.md CHANGED
@@ -1,112 +1,90 @@
1
- [![Build Status](https://secure.travis-ci.org/uploadcare/uploadcare-ruby.png?branch=master)](http://travis-ci.org/uploadcare/uploadcare-ruby)
1
+ # Ruby integration for Uploadcare
2
2
 
3
- A [Ruby](https://www.ruby-lang.org/en/) wrapper for [Uploadcare](https://uploadcare.com).
3
+ ![license](https://img.shields.io/badge/license-MIT-brightgreen.svg)
4
+ [![Build Status][actions-img]][actions-badge]
5
+ [![Uploadcare stack on StackShare][stack-img]][stack]
6
+ <!--[![Coverage Status][coverals-img]][coverals]-->
4
7
 
5
- ## Installation
8
+ [actions-badge]: https://github.com/uploadcare/uploadcare-ruby/actions/workflows/ruby.yml
9
+ [actions-img]: https://github.com/uploadcare/uploadcare-ruby/actions/workflows/ruby.yml/badge.svg
10
+ [coverals-img]: https://coveralls.io/repos/github/uploadcare/uploadcare-ruby/badge.svg?branch=main
11
+ [coverals]: https://coveralls.io/github/uploadcare/uploadcare-ruby?branch=main
12
+ [stack-img]: https://img.shields.io/badge/tech-stack-0690fa.svg?style=flat
13
+ [stack]: https://stackshare.io/uploadcare/stacks/
6
14
 
7
- Installing `uploadcare-ruby` is quite simple and takes a couple of steps.
8
- First of, add the following line to your app's Gemfile:
9
15
 
10
- ```ruby
11
- gem 'uploadcare-ruby'
12
- ```
16
+ Uploadcare Ruby integration handles uploads and further operations with files by
17
+ wrapping Upload and REST APIs.
13
18
 
14
- Once you've added the line, execute this:
19
+ * [Installation](#installation)
20
+ * [Usage](#usage)
21
+ * [Useful links](#useful-links)
15
22
 
16
- ```shell
17
- $ bundle install
18
- ```
23
+ ## Requirements
24
+ * ruby 2.4+
19
25
 
20
- Or that (for manual install):
26
+ ## Compatibility
21
27
 
22
- ```shell
23
- $ gem install uploadcare-ruby
24
- ```
28
+ Note that `uploadcare-ruby` **3.x** is not backward compativble with
29
+ **[2.x](https://github.com/uploadcare/uploadcare-ruby/tree/v2.x)**.
25
30
 
26
- ## Initialization
31
+ ## Installation
27
32
 
28
- Init is simply done through creating an API object.
33
+ Add this line to your application's Gemfile:
29
34
 
30
35
  ```ruby
31
- require 'uploadcare'
36
+ gem 'uploadcare-ruby'
37
+ ```
32
38
 
33
- @api = Uploadcare::Api.new # default settings are used
39
+ And then execute:
34
40
 
35
- @api = Uploadcare::Api.new(settings) # using user-defined settings
36
- ```
41
+ $ bundle
37
42
 
38
- Here's how the default settings look like:
39
-
40
- ``` ruby
41
- {
42
- public_key: 'demopublickey', # you need to override this
43
- private_key: 'demoprivatekey', # you need to override this
44
- upload_url_base: 'https://upload.uploadcare.com',
45
- api_url_base: 'https://api.uploadcare.com',
46
- static_url_base: 'https://ucarecdn.com',
47
- api_version: '0.3',
48
- cache_files: true,
49
- auth_scheme: :secure
50
- }
43
+ If already not, create your project in [Uploadcare dashboard](https://uploadcare.com/dashboard/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby) and copy
44
+ its API keys from there.
45
+
46
+ Set your Uploadcare keys in config file or through environment variables:
47
+ ```bash
48
+ export UPLOADCARE_PUBLIC_KEY=demopublickey
49
+ export UPLOADCARE_SECRET_KEY=demoprivatekey
51
50
  ```
52
51
 
53
- You're free to use both `demopublickey` and `demoprivatekey`
54
- for initial testing purposes. We wipe out files loaded to our
55
- demo account periodically. For a better experience,
56
- consider creating an Uploadcare account. Check out
57
- [this](http://kb.uploadcare.com/article/234-uc-project-and-account)
58
- article to get up an running in minutes.
52
+ Or configure your app yourself if you are using different way of storing keys.
53
+ Gem configuration is available in `Uploadcare.configuration`. Full list of
54
+ settings can be seen in [`lib/uploadcare.rb`](lib/uploadcare.rb)
59
55
 
60
- Please note, in order to use [Upload API](https://uploadcare.com/documentation/upload/)
61
- you will only need the public key alone. However, using
62
- [REST API](https://uploadcare.com/documentation/rest/) requires you to
63
- use both public and private keys for authentication.
64
- While “private key” is a common way to name a key from an
65
- authentication key pair, the actual thing for our `auth-param` is `secret_key`.
56
+ ```ruby
57
+ # your_config_initializer_file.rb
58
+ Uploadcare.config.public_key = 'demopublickey'
59
+ Uploadcare.config.secret_key = 'demoprivatekey'
60
+ ```
66
61
 
67
62
  ## Usage
68
63
 
69
- This section contains practical usage examples. Please note,
70
- everything that follows gets way more clear once you've looked
71
- through our docs [intro](https://uploadcare.com/documentation/).
64
+ This section contains practical usage examples. Please note, everything that
65
+ follows gets way more clear once you've looked through our
66
+ [docs](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
72
67
 
73
- ### Basic usage: uploading a single file, manipulations
68
+ ### Uploading and storing a single file
74
69
 
75
70
  Using Uploadcare is simple, and here are the basics of handling files.
76
71
 
77
- First of, create the API object:
78
-
79
- ```ruby
80
- @api = Uploadcare::Api.new(CONFIG)
81
-
82
- ```
83
-
84
- And yeah, now you can upload a file:
85
-
86
72
  ```ruby
87
73
  @file_to_upload = File.open("your-file.png")
88
74
 
89
- @uc_file = @api.upload(@file_to_upload)
90
- # => #<Uploadcare::Api::File ...
91
- ```
92
-
93
- Then, let's check out UUID and URL of the
94
- file you've just uploaded:
75
+ @uc_file = Uploadcare::Uploader.upload(@file_to_upload)
95
76
 
96
- ```ruby
97
- # file uuid (you'd probably want to store those somewhere)
98
77
  @uc_file.uuid
99
78
  # => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
100
79
 
101
- # url for the file, can be used with your website or app right away
80
+ # URL for the file, can be used with your website or app right away
102
81
  @uc_file.cdn_url
103
82
  # => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
104
83
  ```
105
84
 
106
- Your might then want to store or delete the uploaded file.
107
- Storing files could be crucial if you aren't using the
108
- “Automatic file storing” option for your Uploadcare project.
109
- If not stored manually or automatically, files get deleted
85
+ Your might then want to store or delete the uploaded file. Storing files could
86
+ be crucial if you aren't using the “Automatic file storing” option for your
87
+ Uploadcare project. If not stored manually or automatically, files get deleted
110
88
  within a 24-hour period.
111
89
 
112
90
  ```ruby
@@ -119,519 +97,213 @@ within a 24-hour period.
119
97
  # => #<Uploadcare::Api::File ...
120
98
  ```
121
99
 
122
- ### Uploading a file from URL
100
+ ### Uploads
123
101
 
124
- Now, this one is also quick. Just pass your URL into our API
125
- and you're good to go.
102
+ Uploadcare supports multiple ways to upload files:
126
103
 
127
104
  ```ruby
128
- # the smart upload
129
- @file = @api.upload "http://your.awesome/avatar.jpg"
130
- # => #<Uploadcare::Api::File ...
131
-
132
- # use this one if you want to explicitly upload from URL
133
- @file = @api.upload_from_url "http://your.awesome/avatar.jpg"
134
- # => #<Uploadcare::Api::File ...
105
+ # Smart upload - detects type of passed object and picks appropriate upload method
106
+ Uploadcare::Uploader.upload('https://placekitten.com/96/139')
135
107
  ```
136
- Keep in mind that providing invalid URL
137
- will raise `ArgumentError`.
138
108
 
139
- ### Uploading multiple files
140
-
141
- Uploading multiple files is as simple as passing an array
142
- of `File` instances into our API.
109
+ There are explicit ways to select upload type:
143
110
 
144
111
  ```ruby
145
- file1 = File.open("path/to/your/file.png")
146
- file2 = File.open("path/to/your/another-file.png")
147
- files = [file1, file2]
148
-
149
- @uc_files = @api.upload files
150
- # => [#<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40">,
151
- # #<Uploadcare::Api::File uuid="96cdc400-adc3-435b-9c94-04cd87633fbb">]
152
- ```
153
-
154
- In case of multiple input, the respective output would also be an array.
155
- You can iterate through the array to address to single files.
156
- You might also want to request more info about a file using `load_data`.
112
+ files = [File.open('1.jpg'), File.open('1.jpg']
113
+ Uploadcare::Uploader.upload_files(files)
157
114
 
158
- ```ruby
159
- @uc_files[0]
160
- # => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40">
115
+ Uploadcare::Uploader.upload_from_url('https://placekitten.com/96/139')
161
116
 
162
- @uc_files[1].load_data
163
- # => #<Uploadcare::Api::File uuid="96cdc400-adc3-435b-9c94-04cd87633fbb", original_file_url="https://ucarecdn.com/96cdc400-adc3-435b-9c94-04cd87633fbb/samuelzeller118195.jpg", image_info={"width"=>4896, "geo_location"=>nil, "datetime_original"=>nil, "height"=>3264}, ....>
117
+ # multipart upload - can be useful for files bigger than 10 mb
118
+ Uploadcare::Uploader.multipart_upload(File.open('big_file.bin'))
164
119
  ```
165
120
 
166
- ### `File` object
121
+ ### Upload options
167
122
 
168
- Now that we've already outlined using arrays of `File` instances
169
- to upload multiple files, let's fix on the `File` itself.
170
- It's the the primary object for Uploadcare API.
171
- Basically, it's an avatar for a file you uploaded.
172
- And all the further operations are performed using this avatar,
173
- the `File` object.
123
+ You can override global [`:autostore`](#initialization) option for each upload request:
174
124
 
175
125
  ```ruby
176
- @file_to_upload = File.open("your-file.png")
177
-
178
- @uc_file = @api.upload(@file_to_upload)
179
- # => #<Uploadcare::Api::File ...
180
-
181
- @uc_file.uuid
182
- # => "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
183
-
184
- @uc_file.cdn_url
185
- # => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
126
+ @api.upload(files, store: true)
127
+ @api.upload_from_url(url, store: :auto)
186
128
  ```
187
129
 
188
- Please note, all the data associated with files is only accessible
189
- through separate HTTP requests only. So if you don't specifically
190
- need file data (filenames, image dimensions, etc.), you'll be just
191
- fine with using `:uuid` and `:cdn_url` methods for file output:
192
-
193
- ```erb
194
- <img src="#{@file.cdn_url}"/>
195
- ```
196
-
197
- Great, we've just lowered a precious loading time.
198
- However, if you do need the data, you can always request
199
- it manually:
200
-
130
+ ### Api
131
+ Most methods are also available through `Uploadcare::Api` object:
201
132
  ```ruby
202
- @uc_file.load_data
133
+ # Same as Uploadcare::Uploader.upload
134
+ Uploadcare::Api.upload('https://placekitten.com/96/139')
203
135
  ```
204
136
 
205
- That way your file object will respond to any method described
206
- in [API docs](https://uploadcare.com/documentation/rest/#file).
207
- Basically, that's an an OpenStruct, so you know what to do:
137
+ ### Entity object
208
138
 
209
- ```ruby
210
- @uc_file.original_filename
211
- # => "logo.png"
212
-
213
- @uc_file.image_info
214
- # => {"width"=>397, "geo_location"=>nil, "datetime_original"=>nil, "height"=>81}
215
- ```
139
+ Entities are representations of objects in Uploadcare cloud.
216
140
 
217
- ### `File` object from UUID or CDN URL
141
+ #### File
218
142
 
219
- `File` objects are needed to manipulate files on our CDN.
220
- The usual case would be you as a client storing file UUIDs
221
- or CDN URLs somewhere on your side, e.g. in a database.
222
- This is how you can use those to create `File` objects:
143
+ File entity contains its metadata.
223
144
 
224
145
  ```ruby
225
- # file object from UUID
226
- @file = @api.file "dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
227
- # => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
228
-
229
- # file object from CDN URL
230
- @file = @api.file "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/"
231
- # => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
232
-
233
- # note, files you generate won't be loaded on init,
234
- # you'll need to load those manually
235
- @file.is_loaded?
236
- # => false
237
- ```
238
-
239
- ### Operations
240
-
241
- Another way to mainpulate files on CDN is through operations.
242
- This is particularly useful for images.
243
- We've got on-the-fly crop, resize, rotation, format conversions, and
244
- [more](https://uploadcare.com/documentation/cdn/).
245
- Image operations are there to help you build responsive designs,
246
- generate thumbnails and galleries, change formats, etc.
247
- Currently, this gem has no specific methods for image operations,
248
- we're planning to implement those in further versions.
249
- However, we do support applying image operations through
250
- adding them to CDN URLs. That's an Uploadcare CDN-native
251
- way described in our [docs](https://uploadcare.com/documentation/cdn/).
146
+ @file = Uploadcare::File.file('FILE_ID_IN_YOUR_PROJECT')
147
+ {"datetime_removed"=>nil,
148
+ "datetime_stored"=>"2020-01-16T15:03:15.315064Z",
149
+ "datetime_uploaded"=>"2020-01-16T15:03:14.676902Z",
150
+ "image_info"=>
151
+ {"color_mode"=>"RGB",
152
+ "orientation"=>nil,
153
+ "format"=>"JPEG",
154
+ "sequence"=>false,
155
+ "height"=>183,
156
+ "width"=>190,
157
+ "geo_location"=>nil,
158
+ "datetime_original"=>nil,
159
+ "dpi"=>nil},
160
+ "is_image"=>true,
161
+ "is_ready"=>true,
162
+ "mime_type"=>"image/jpeg",
163
+ "original_file_url"=>
164
+ "https://ucarecdn.com/FILE_ID_IN_YOUR_PROJECT/imagepng.jpeg",
165
+ "original_filename"=>"image.png.jpeg",
166
+ "size"=>5345,
167
+ "url"=>
168
+ "https://api.uploadcare.com/files/FILE_ID_IN_YOUR_PROJECT/",
169
+ "uuid"=>"8f64f313-e6b1-4731-96c0-6751f1e7a50a"}
170
+
171
+ @file.store # stores file, returns updated metadata
172
+
173
+ @file.delete #deletes file. Returns updated metadata
174
+ ```
175
+
176
+ Metadata of deleted files is stored permanently.
177
+
178
+ #### FileList
179
+
180
+ `Uploadcare::Entity::FileList` represents the whole collection of files (or it's
181
+ subset) and provides a way to iterate through it, making pagination transparent.
182
+ FileList objects can be created using `Uploadcare::Entity.file_list` method.
252
183
 
253
184
  ```ruby
254
- @file = @api.file "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/-/crop/150x150/center/-/format/png/"
255
- # => #<Uploadcare::Api::File uuid="dc99200d-9bd6-4b43-bfa9-aa7bfaefca40"
256
-
257
- @file.operations
258
- # => ["crop/150x150/center", "format/png"]
259
-
260
- # note that by default :cdn_url method returns URLs with no operations:
261
- @file.cdn_url
262
- # => "https://ucarecdn.com/dc99200d-9bd6-4b43-bfa9-aa7bfaefca40/""
263
-
264
- # you can pass "true" into the :cdn_url method to get URL including operations:
265
- @file.cdn_url(true)
266
- # => "https://ucarecdn.com/a8775cf7-0c2c-44fa-b071-4dd48637ecac/-/crop/150x150/center/-/format/png/"
185
+ @list = Uploadcare::Entity.file_list
186
+ # Returns instance of Uploadcare::Api::FileList
187
+ <Hashie::Mash
188
+ next=nil
189
+ per_page=100
190
+ previous=nil
191
+ results=[
192
+ # Array of Entity::File
193
+ ]
194
+ total=8>
195
+ # load last page of files
196
+ @files = @list.files
197
+ # load all files
198
+ @all_files = @list.load
199
+ ```
200
+
201
+ This method accepts some options to controll which files should be fetched and
202
+ how they should be fetched:
203
+
204
+ - **:limit** — Controls page size. Accepts values from 1 to 1000, defaults to 100.
205
+ - **:stored** — Can be either `true` or `false`. When true, file list will contain only stored files. When false — only not stored.
206
+ - **:removed** — Can be either `true` or `false`. When true, file list will contain only removed files. When false — all except removed. Defaults to false.
207
+ - **:ordering** — Controls the order of returned files. Available values: `datetime_updated`, `-datetime_updated`, `size`, `-size`. Defaults to `datetime_uploaded`. More info can be found [here](https://uploadcare.com/documentation/rest/#file-files/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
208
+ - **:from** — Specifies the starting point for a collection. Resulting collection will contain files from the given value and to the end in a direction set by an **ordering** option. When files are ordered by `datetime_updated` in any direction, accepts either a `DateTime` object or an ISO 8601 string. When files are ordered by size, accepts non-negative integers (size in bytes). More info can be found [here](https://uploadcare.com/documentation/rest/#file-files/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby).
209
+
210
+ Options used to create a file list can be accessed through `#options` method.
211
+ Note that, once set, they don't affect file fetching process anymore and are
212
+ stored just for your convenience. That is why they are frozen.
267
213
 
268
- # there also are specific methods to either dump or include image operations
269
- # in the output URL:
270
- @file.cdn_url_with_operations
271
- @file.cdn_url_without_operations
214
+ ```ruby
215
+ options = {
216
+ limit: 10,
217
+ stored: true,
218
+ ordering: '-datetime_uploaded',
219
+ from: "2017-01-01T00:00:00",
220
+ }
221
+ @list = @api.file_list(options)
272
222
  ```
273
223
 
274
- While there's no operation wrapper, the best way of handling operations
275
- is through adding them to URLs as strings:
276
-
224
+ To simply get all associated objects:
277
225
  ```ruby
278
- <img src="#{file.cdn_url}-/crop/#{width}x#{height}/center/"/>
279
- # or something like that
226
+ @list.all # => returns Array of Files
280
227
  ```
281
228
 
282
- ### Copying files
283
-
284
- You can also create file copies using our API.
285
- There are multiple ways of creating those.
286
- Also, copying is important for image files because
287
- it allows you to “apply” all the CDN operations
288
- specified in the source URL to a separate static image.
289
-
290
- First of all, a copy of your file can be put in the Uploadcare storage.
291
- This is called “internal copy”, and here's how it works:
229
+ ##### Pagination
292
230
 
231
+ Initially, `FileList` is a paginated collection. It can be navigated using following methods:
293
232
  ```ruby
294
- @uc_file.internal_copy
295
-
296
- # =>
297
- {
298
- "type"=>"file",
299
- "result"=> {
300
- "uuid"=>"a191a3df-2c43-4939-9590-784aa371ad6d",
301
- "original_file_url"=>"https://ucarecdn.com/a191a3df-2c43-4939-9590-784aa371ad6d/19xldj.jpg",
302
- "image_info"=>nil,
303
- "datetime_stored"=>nil,
304
- "mime_type"=>"application/octet-stream",
305
- "is_ready"=>true,
306
- "url"=>"https://api.uploadcare.com/files/a191a3df-2c43-4939-9590-784aa371ad6d/",
307
- "original_filename"=>"19xldj.jpg",
308
- "datetime_uploaded"=>"2017-02-10T14:14:18.690581Z",
309
- "size"=>0,
310
- "is_image"=>nil,
311
- "datetime_removed"=>nil,
312
- "source"=>"/4ea293d5-153f-422f-a24e-350237109606/"
313
- }
314
- }
233
+ @file_list = Uploadcare::Entity::FileList.file_list
234
+ # Let's assume there are 250 files in cloud. By default, UC loads 100 files. To get next 100 files, do:
235
+ @next_page = @file_list.next_page
236
+ # To get previous page:
237
+ @previous_page = @next_page.previous_page
315
238
  ```
316
239
 
317
- Once the procedure is complete, a copy would be a separate file
318
- with its own UUID and attributes.
319
-
320
- `#internal_copy` can optionally be used with the options hash argument.
321
- The available options are:
322
-
323
- - *store*
324
-
325
- By default a copy is created without “storing”.
326
- Which means it will be deleted within a 24-hour period.
327
- You can make your output copy permanent by passing the
328
- `store: true` option to the `#internal_copy` method.
329
-
330
- Example:
331
-
332
- ```ruby
333
- @uc_file.internal_copy(store: true)
334
- ```
335
-
336
- - *strip_operations*
337
-
338
- If your file is an image and you applied some operations to it,
339
- then by default the same set of operations is also applied to a copy.
340
- You can override this by passing `strip_operations: true` to the
341
- `#internal_copy` method.
342
-
343
- Example:
344
-
345
- ```ruby
346
- file = @api.file "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/-/resize/50x50/"
347
- file.internal_copy
348
- # => This will trigger POST /files/ with {"source": "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/-/resize/50x50/"} in the body
349
- file.internal_copy(strip_operations: true)
350
- # => This will trigger POST /files/ with {"source": "https://ucarecdn.com/24626d2f-3f23-4464-b190-37115ce7742a/"} in the body
351
- ```
352
-
353
- Another option is copying your file to a custom storage.
354
- We call it “external copy” and here's the usage example:
355
-
240
+ Alternatively, it's possible to iterate through full list of groups or files with `each`:
356
241
  ```ruby
357
- @uc_file.external_copy('my_custom_storage_name')
358
-
359
- # =>
360
- {
361
- "type"=>"url",
362
- "result"=>"s3://my_bucket_name/c969be02-9925-4a7e-aa6d-b0730368791c/view.png"
363
- }
242
+ @list.each do |file|
243
+ p file.url
244
+ end
364
245
  ```
365
246
 
366
- First argument of the `#external_copy` method is a name of
367
- a custom destination storage for your file.
368
-
369
- There's also an optional second argument — options hash. The available options are:
370
-
371
- - *make_public*
247
+ #### Group
372
248
 
373
- Make a copy available via public links. Can be either `true` or `false`.
374
-
375
- - *pattern*
376
-
377
- Name pattern for a copy. If the parameter is omitted, custom storage pattern is used.
378
-
379
- - *strip_operations*
380
-
381
- Same as for `#internal_copy`
382
-
383
- You might want to learn more about
384
- [storage options](https://uploadcare.com/documentation/storages/) or
385
- [copying files](https://uploadcare.com/documentation/rest/#files-post)
386
- with Uploadcare.
387
-
388
- ### `Group` object
389
-
390
- Groups are structures intended to organize sets of separate files.
391
- Each group is assigned UUID.
392
- Note, group UUIDs include a `~#{files_count}` part at the end.
249
+ Groups are structures intended to organize sets of separate files. Each group is
250
+ assigned UUID. Note, group UUIDs include a `~#{files_count}` part at the end.
393
251
  That's a requirement of our API.
394
252
 
395
253
  ```ruby
396
254
  # group can be created from an array of Uploadcare files
397
255
  @files_ary = [@file, @file2]
398
- @files = @api.upload @files_ary
399
- @group = @api.create_group @files
400
- # => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
401
-
402
- # another way to from a group is via an array of strings holding UUIDs
403
- @uuids_ary = ["c969be02-9925-4a7e-aa6d-b0730368791c", "c969be02-9925-4a7e-aa6d-b0730368791c"]
404
- @group = @api.create_group @uuids_ary
405
- # => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
406
-
407
- # also, you can create a group object via group UUID
408
- @group_uloaded = @api.group "#{uuid}"
256
+ @files = Uploadcare::Uploader.upload @files_ary
257
+ @group = Uploadcare::Group.create @files
409
258
  ```
410
259
 
411
- As with files, groups created via UUIDs are not loaded by default.
412
- You need to load the data manually, as it requires a separate
413
- HTTP GET request. New groups created with the `:create_group` method
414
- are loaded by default.
260
+ #### GroupList
261
+ `GroupList` is a list of `Group`
415
262
 
416
263
  ```ruby
417
- @group = @api.group "#{uuid}"
418
-
419
- @group.is_loaded?
420
- # => false
421
-
422
- @group.load_data
423
- # => #<Uploadcare::Api::Group uuid="0d192d66-c7a6-4465-b2cd-46716c5e3df3~2", files_count=2 ...
424
-
425
- # once a group is loaded, you can use any methods described in our API docs
426
- # the files within a loaded group are loaded by default
427
- @group.files
428
- # => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
429
- # ... #{files_count} of them ...
430
- # #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
264
+ @group_list = Uploadcare::GroupList.list
265
+ # To get an array of groups:
266
+ @groups = @group_list.all
431
267
  ```
432
268
 
433
- Check out our docs to learn more about
434
- [groups](https://uploadcare.com/documentation/rest/#group).
435
-
436
- ### File lists and pagination
437
-
438
- File list is a paginated collection of files. Such lists are created
439
- to better represent the contents of your project.
440
- For this gem, a file list would be a single page containing
441
- 20 files (you can override the number).
442
- There also are methods for navigating through pages.
443
- You can find more info about pagination
444
- [here](https://uploadcare.com/documentation/rest/#pagination).
445
-
446
- ```ruby
447
- @list = @api.file_list 1 # page number, 1 is the default
448
- # => #<Uploadcare::Api::FileList ....
449
-
450
-
451
- # method :results returns an array of files
452
- @list.results
453
- # => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
454
- # ... 20 of them ...
455
- # #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
269
+ This is a paginated list, so [pagination](#Pagination) methods apply
456
270
 
271
+ #### Webhook
272
+ https://uploadcare.com/docs/api_reference/rest/webhooks/
457
273
 
458
- # note, every file is already loaded
459
- @list.results[1].is_loaded?
460
- # => true
461
-
462
-
463
- # we've also added some shortcuts
464
- @list.to_a
465
- # => [#<Uploadcare::Api::File uuid="24626d2f-3f23-4464-b190-37115ce7742a" ...>,
466
- # ... 20 of them ...
467
- # #<Uploadcare::Api::File uuid="7bb9efa4-05c0-4f36-b0ef-11a4221867f6" ...>]
468
-
469
- @list[3]
470
- # => #<Uploadcare::Api::File ....
471
- ```
472
-
473
- Here's how we handle navigating through pages:
274
+ You can use webhooks to provide notifications about your uploads to target urls.
275
+ This gem lets you create and manage webhooks.
474
276
 
475
277
  ```ruby
476
- @list = @api.files_list 3
477
-
478
- @list.next_page
479
- # => #<Uploadcare::Api::FileList page=4 ....
480
-
481
- @list.previous_page
482
- # => #<Uploadcare::Api::FileList page=2 ....
483
-
484
- @list.go_to 5
485
- # => #<Uploadcare::Api::FileList page=5 ....
486
-
487
- # of course, you can go with any of the methods
488
- # described in our API docs
489
- # total pages
490
- @list.pages
491
- # => 16
492
-
493
- # current page
494
- @list.page
495
- # => 3
496
-
497
- # files per page
498
- @list.per_page
499
- # => 20
500
-
501
- # total files in a project
502
- @list.total
503
- # => 308
278
+ Uploadcare::Webhook.create('example.com/listen', event: 'file.uploaded')
504
279
  ```
505
280
 
506
- ### `Project` object
281
+ #### Project
507
282
 
508
- `Project` provides basic info about the connected Uploadcare project.
509
- That object is also an OpenStruct, so every methods out of
510
- [these](https://uploadcare.com/documentation/rest/#project) will work.
283
+ `Project` provides basic info about the connected Uploadcare project. That
284
+ object is also an Hashie::Mash, so every methods out of
285
+ [these](https://uploadcare.com/documentation/rest/#project/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby) will work.
511
286
 
512
287
  ```ruby
513
- project = @api.project
288
+ @project = Uploadcare::Project.project
514
289
  # => #<Uploadcare::Api::Project collaborators=[], name="demo", pub_key="demopublickey", autostore_enabled=true>
515
290
 
516
- project.name
291
+ @project.name
517
292
  # => "demo"
518
293
 
519
- p.collaborators
294
+ @project.collaborators
520
295
  # => []
521
296
  # while that one was empty, it usually goes like this:
522
297
  # [{"email": collaborator@gmail.com, "name": "Collaborator"}, {"email": collaborator@gmail.com, "name": "Collaborator"}]
523
298
  ```
524
299
 
525
- ### Raw API
526
-
527
- Raw API is a simple interface allowing you to make
528
- custom requests to Uploadcare REST API.
529
- It's mainly used when you want a low-level control
530
- over your app.
531
-
532
- ```ruby
533
- # here's how you make any requests
534
- @api.request :get, "/files/", {page: 2}
535
-
536
- # and there also are shortcuts for methods
537
- @api.get '/files', {page: 2}
538
-
539
- @api.post ...
540
-
541
- @api.put ...
542
-
543
- @api.delete ...
544
-
545
- ```
546
-
547
- All of the raw API methods return a parsed JSON response
548
- or raise an error (handling those is done on your side in the case).
549
-
550
- ### Error handling
551
-
552
- Starting from the version 1.0.2, we've got have custom exceptions
553
- that will be raised in case the Uploadcare service returns
554
- something with 4xx or 5xx HTTP status.
555
-
556
- Check out the list of custom errors:
557
-
558
- ```ruby
559
- 400 => Uploadcare::Error::RequestError::BadRequest,
560
- 401 => Uploadcare::Error::RequestError::Unauthorized,
561
- 403 => Uploadcare::Error::RequestError::Forbidden,
562
- 404 => Uploadcare::Error::RequestError::NotFound,
563
- 406 => Uploadcare::Error::RequestError::NotAcceptable,
564
- 408 => Uploadcare::Error::RequestError::RequestTimeout,
565
- 422 => Uploadcare::Error::RequestError::UnprocessableEntity,
566
- 429 => Uploadcare::Error::RequestError::TooManyRequests,
567
- 500 => Uploadcare::Error::ServerError::InternalServerError,
568
- 502 => Uploadcare::Error::ServerError::BadGateway,
569
- 503 => Uploadcare::Error::ServerError::ServiceUnavailable,
570
- 504 => Uploadcare::Error::ServerError::GatewayTimeout
571
- ```
572
-
573
- That's how you handle a particular error
574
- (in this case, a “404: Not Found” error):
575
-
576
- ```ruby
577
- begin
578
- @connection.send :get, '/random_url/', {}
579
- rescue Uploadcare::Error::RequestError::NotFound => e
580
- nil
581
- end
582
- ```
583
-
584
- Handling any request error (covers all 4xx status codes):
585
-
586
- ```ruby
587
- begin
588
- @connection.send :get, '/random_url/', {}
589
- rescue Uploadcare::Error::RequestError => e
590
- nil
591
- end
592
- ```
593
-
594
- Handling any Uploadcare service error:
595
-
596
- ```ruby
597
- begin
598
- @connection.send :get, '/random_url/', {}
599
- rescue Uploadcare::Error => e
600
- nil
601
- end
602
- ```
603
-
604
- Since many of the above listed things depend on Uploadcare servers,
605
- errors might occasionally occur. Be prepared to handle those.
606
-
607
- ## Testing
608
-
609
- For testing purposes, run `bundle exec rspec`.
610
-
611
- Please note, if you're willing to run tests using your own keys,
612
- make a `spec/config.yml` file containing the following:
613
-
614
- ```yaml
615
- public_key: 'PUBLIC KEY'
616
- private_key: 'PRIVATE KEY'
617
- ```
618
-
619
- ## Contributors
620
-
621
- This is open source so fork, hack, request a pull — get a discount.
622
-
623
- - [@romanonthego](https://github.com/romanonthego)
624
- - [@vizvamitra](https://github.com/vizvamitra)
625
- - [@dmitry-mukhin](https://github.com/dmitry-mukhin)
626
- - [@zenati](https://github.com/zenati)
627
- - [@renius](https://github.com/renius)
628
-
629
- ## Security issues
630
-
631
- If you think you ran into something in Uploadcare libraries
632
- which might have security implications, please hit us up at
633
- [bugbounty@uploadcare.com](mailto:bugbounty@uploadcare.com)
634
- or Hackerone.
300
+ ## Useful links
635
301
 
636
- We'll contact you personally in a short time to fix an issue
637
- through co-op and prior to any public disclosure.
302
+ * [Development](https://github.com/uploadcare/uploadcare-ruby/blob/main/DEVELOPMENT.md)
303
+ * [Uploadcare documentation](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)
304
+ * [Upload API reference](https://uploadcare.com/api-refs/upload-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)
305
+ * [REST API reference](https://uploadcare.com/api-refs/rest-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-ruby)
306
+ * [Changelog](./CHANGELOG.md)
307
+ * [Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)
308
+ * [Security policy](https://github.com/uploadcare/uploadcare-ruby/security/policy)
309
+ * [Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)