Skip to content

Commit 7c3de4b

Browse files
fern-supportfern-support
authored
README updates with a license change to match the repo in gemspec file (#172)
* README updates with a license change to match the repoin gemspec file * Removing duplicate block code start
1 parent 15622f4 commit 7c3de4b

File tree

2 files changed

+218
-1
lines changed

2 files changed

+218
-1
lines changed

‎README.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Square Ruby Library
2+
3+
[![Build](https://github.com/square/square-ruby-sdk/actions/workflows/ruby.yml/badge.svg)](https://github.com/square/square-ruby-sdk/actions/workflows/ruby.yml)
4+
[![Gem version](https://badge.fury.io/rb/square.rb.svg?new)](https://badge.fury.io/rb/square.rb)
5+
6+
The Square Ruby library provides convenient access to the Square API from Ruby.
7+
8+
## Requirements
9+
10+
Use of the Square Ruby SDK requires:
11+
12+
* Ruby 2.7+
13+
14+
## Installation
15+
16+
For more information, see [Set Up Your Square SDK for a Ruby Project](https://developer.squareup.com/docs/sdks/ruby/setup-project).
17+
18+
## Reference
19+
20+
For more information, see [Full Ruby Guide](https://developer.squareup.com/docs/sdks/ruby).
21+
22+
## Versioning
23+
24+
The Square Ruby SDK version is managed through the gem version. To use a specific version:
25+
26+
```bash
27+
gem install square.rb -v 44.0.0
28+
```
29+
30+
Or in your Gemfile:
31+
```ruby
32+
gem 'square.rb', '~> 44.0.0'
33+
```
34+
35+
## Usage
36+
37+
For more information, see [Using the Square Ruby SDK](https://developer.squareup.com/docs/sdks/ruby/using-ruby-sdk).
38+
39+
## Legacy SDK
40+
41+
While the new SDK has a lot of improvements, we at Square understand that it takes time to upgrade when there are breaking changes.
42+
To make the migration easier, the new SDK also exports the legacy SDK as `square_legacy`. Here's an example of how you can use the
43+
legacy SDK alongside the new SDK inside a single file:
44+
45+
```ruby
46+
# Load both SDKs
47+
require 'square'
48+
require 'square_legacy'
49+
50+
# Initialize new SDK client
51+
new_client = Square::Client.new(
52+
access_token: 'YOUR_SQUARE_ACCESS_TOKEN'
53+
)
54+
55+
# Initialize legacy SDK client
56+
legacy_client = SquareLegacy::Client.new(
57+
bearer_auth_credentials: {
58+
access_token: 'YOUR_SQUARE_ACCESS_TOKEN'
59+
}
60+
)
61+
62+
# Use new SDK for newer features
63+
locations = new_client.locations.get_locations.data.locations
64+
65+
# Use legacy SDK for specific legacy functionality
66+
legacy_payment = legacy_client.payments_api.create_payment(
67+
body: {
68+
source_id: 'example_1234567890',
69+
idempotency_key: SecureRandom.uuid,
70+
amount_money: {
71+
amount: 100,
72+
currency: 'USD'
73+
}
74+
}
75+
)
76+
```
77+
78+
We recommend migrating to the new SDK using the following steps:
79+
80+
1. Update your square.rb: `gem update square.rb`
81+
2. Search and replace all requires from `'square'` to `'square_legacy'`
82+
3. Update all client initializations from
83+
```ruby
84+
client = Square::Client.new(access_token: 'token')
85+
```
86+
to
87+
```ruby
88+
client = SquareLegacy::Client.new(
89+
bearer_auth_credentials: { access_token: 'token' }
90+
)
91+
```
92+
4. Gradually migrate over to the new SDK by importing it from the `'square'` import.
93+
94+
## Request And Response Types
95+
96+
The SDK exports all request and response types as Ruby classes. Simply require them with the
97+
following namespace:
98+
99+
```ruby
100+
require 'square'
101+
102+
# Create a request object
103+
request = Square::CreateMobileAuthorizationCodeRequest.new(
104+
location_id: 'YOUR_LOCATION_ID'
105+
)
106+
```
107+
108+
## Exception Handling
109+
110+
When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
111+
will be raised.
112+
113+
```ruby
114+
require 'square'
115+
116+
begin
117+
response = client.payments.create(...)
118+
rescue Square::ApiError => e
119+
puts "Status Code: #{e.status_code}"
120+
puts "Message: #{e.message}"
121+
puts "Body: #{e.body}"
122+
end
123+
```
124+
125+
## Pagination
126+
127+
List endpoints are paginated. The SDK provides methods to handle pagination:
128+
129+
```ruby
130+
require 'square'
131+
132+
client = Square::Client.new(access_token: "YOUR_TOKEN")
133+
134+
# Get all items using pagination
135+
response = client.bank_accounts.list
136+
all_bank_accounts = []
137+
138+
while response.data.bank_accounts.any?
139+
all_bank_accounts.concat(response.data.bank_accounts)
140+
141+
# Check if there are more pages
142+
if response.cursor
143+
response = client.bank_accounts.list(cursor: response.cursor)
144+
else
145+
break
146+
end
147+
end
148+
149+
puts "Total bank accounts: #{all_bank_accounts.length}"
150+
```
151+
152+
## Advanced
153+
154+
### Additional Headers
155+
156+
If you would like to send additional headers as part of the request, use the `headers` request option.
157+
158+
```ruby
159+
response = client.payments.create(..., {
160+
headers: {
161+
'X-Custom-Header' => 'custom value'
162+
}
163+
})
164+
```
165+
166+
### Receive Extra Properties
167+
168+
Every response includes any extra properties in the JSON response that were not specified in the type.
169+
This can be useful for API features not present in the SDK yet.
170+
171+
You can receive and interact with the extra properties by accessing the raw response data:
172+
173+
```ruby
174+
response = client.locations.create(...)
175+
176+
# Access the raw response data
177+
location_data = response.data.to_h
178+
179+
# Then access the extra property by its name
180+
undocumented_property = location_data['undocumentedProperty']
181+
```
182+
183+
### Retries
184+
185+
The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
186+
as the request is deemed retriable and the number of retry attempts has not grown larger than the configured
187+
retry limit (default: 2).
188+
189+
A request is deemed retriable when any of the following HTTP status codes is returned:
190+
191+
- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
192+
- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
193+
- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
194+
195+
Use the `max_retries` request option to configure this behavior.
196+
197+
```ruby
198+
response = client.payments.create(..., {
199+
max_retries: 0 # override max_retries at the request level
200+
})
201+
```
202+
203+
### Timeouts
204+
205+
The SDK defaults to a 60 second timeout. Use the `timeout_in_seconds` option to configure this behavior.
206+
207+
```ruby
208+
response = client.payments.create(..., {
209+
timeout_in_seconds: 30 # override timeout to 30s
210+
})
211+
```
212+
213+
## Contributing
214+
215+
While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!
216+
217+
On the other hand, contributions to the README are always very welcome!

‎square.gemspec‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Gem::Specification.new do |s|
66
s.authors = ['Square Developer Platform']
77
s.email = ['[email protected]']
88
s.homepage = 'https://squareup.com/developers'
9-
s.licenses = ['Apache-2.0']
9+
s.licenses = ['MIT']
1010
s.add_dependency('apimatic_core_interfaces', '~> 0.2.1')
1111
s.add_dependency('apimatic_core', '~> 0.3.11')
1212
s.add_dependency('apimatic_faraday_client_adapter', '~> 0.1.4')

0 commit comments

Comments
 (0)