Skip to content

Commit 09952c4

Browse files
andyw8andyw8
authored
Move older Breaking Changes notes out of README (Shopify#967)
1 parent 6460530 commit 09952c4

File tree

2 files changed

+112
-105
lines changed

2 files changed

+112
-105
lines changed

‎BREAKING_CHANGES_FOR_OLDER_VERSIONS.md

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Breaking changes for older versions
2+
3+
The breaking changes for the previous major release are listed in the main [README](README.md).
4+
The breaking changes for older major releases are listed below.
5+
6+
### Breaking change notice for version 8.0.0
7+
8+
Version 7.0.0 introduced ApiVersion, and known versions were hardcoded into the gem. Manually defining API versions is no longer required for versions not listed in the gem. Version 8.0.0 removes the following:
9+
* `ShopifyAPI::ApiVersion::Unstable`
10+
* `ShopifyAPI::ApiVersion::Release`
11+
* `ShopifyAPI::ApiVersion.define_version`
12+
13+
The following methods on `ApiVersion` have been deprecated:
14+
- `.coerce_to_version` deprecated. use `.find_version`
15+
- `.define_known_versions` deprecated. Use `.fetch_known_versions`
16+
- `.clear_defined_versions` deprecated. Use. `.clear_known_versions`
17+
- `.latest_stable_version` deprecated. Use `ShopifyAPI::Meta.admin_versions.find(&:latest_supported)` (this fetches info from Shopify servers. No authentication required.)
18+
- `#name` deprecated. Use `#handle`
19+
- `#stable?` deprecated. Use `#supported?`
20+
21+
Version 8.0.0 introduces a _version lookup mode_. By default, `ShopifyAPI::ApiVersion.version_lookup_mode` is `:define_on_unknown`. When setting the api_version on `Session` or `Base`, the `api_version` attribute takes a version handle (i.e. `'2019-07'` or `:unstable`) and sets an instance of `ShopifyAPI::ApiVersion` matching the handle. When the version_lookup_mode is set to `:define_on_unknown`, any handle will naïvely create a new `ApiVersion` if the version is not in the known versions returned by `ShopifyAPI::ApiVersion.versions`.
22+
23+
To ensure you're setting only known and active versions, call :
24+
25+
```ruby
26+
ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
27+
ShopifyAPI::ApiVersion.fetch_known_versions
28+
```
29+
30+
Known and active versions are fetched from https://app.shopify.com/services/apis.json and cached. Trying to use a version outside this cached set will raise an error. To switch back to naïve lookup and create a version if one is not found, call `ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown`.
31+
32+
### Breaking change notice for version 7.0.0
33+
34+
#### Changes to ShopifyAPI::Session
35+
When creating sessions, `api_version`is now required and uses keyword arguments.
36+
37+
To upgrade your use of ShopifyAPI you will need to make the following changes.
38+
39+
```ruby
40+
ShopifyAPI::Session.new(domain, token, extras)
41+
```
42+
is now
43+
```ruby
44+
ShopifyAPI::Session.new(domain: domain, token: token, api_version: api_version, extras: extras)
45+
```
46+
Note `extras` is still optional. The other arguments are required.
47+
48+
```ruby
49+
ShopifyAPI::Session.temp(domain, token, extras) do
50+
...
51+
end
52+
```
53+
is now
54+
```ruby
55+
ShopifyAPI::Session.temp(domain: domain, token: token, api_version: api_version) do
56+
...
57+
end
58+
```
59+
60+
For example, if you want to use the `2019-04` version, you will create a session like this:
61+
```ruby
62+
session = ShopifyAPI::Session.new(domain: domain, token: token, api_version: '2019-04')
63+
```
64+
if you want to use the `unstable` version, you will create a session like this:
65+
```ruby
66+
session = ShopifyAPI::Session.new(domain: domain, token: token, api_version: :unstable)
67+
```
68+
69+
#### Changes to how to define resources
70+
71+
If you have defined or customized Resources, classes that extend `ShopifyAPI::Base`:
72+
The use of `self.prefix =` has been deprecated; you should now use `self.resource =` and not include `/admin`.
73+
For example, if you specified a prefix like this before:
74+
```ruby
75+
class MyResource < ShopifyAPI::Base
76+
self.prefix = '/admin/shop/'
77+
end
78+
```
79+
You will update this to:
80+
```ruby
81+
class MyResource < ShopifyAPI::Base
82+
self.resource_prefix = 'shop/'
83+
end
84+
```
85+
86+
#### URL construction
87+
88+
If you have specified any full paths for API calls in find
89+
```ruby
90+
def self.current(options={})
91+
find(:one, options.merge(from: "/admin/shop.#{format.extension}"))
92+
end
93+
```
94+
would be changed to
95+
96+
```ruby
97+
def self.current(options = {})
98+
find(:one, options.merge(
99+
from: api_version.construct_api_path("shop.#{format.extension}")
100+
))
101+
end
102+
```
103+
104+
#### URLs that have not changed
105+
106+
- OAuth URLs for `authorize`, getting the `access_token` from a code, `access_scopes`, and using a `refresh_token` have _not_ changed.
107+
- get: `/admin/oauth/authorize`
108+
- post: `/admin/oauth/access_token`
109+
- get: `/admin/oauth/access_scopes`
110+
- URLs for the merchant’s web admin have _not_ changed. For example: to send the merchant to the product page the url is still `/admin/product/<id>`

‎README.md

+2-105
Original file line numberDiff line numberDiff line change
@@ -115,112 +115,9 @@ With this, a lot changed in how apps access the library. Here are the updates yo
115115
| `order = Order.new(<id>)`<br/>`order.post(:close)` | `order = Order.new(session:)`<br/>`order.close()` |
116116
| `order = Order.new(<id>)`<br/>`order.delete` | `Order.delete(id: <id>, session:)` |
117117

118-
### Breaking change notice for version 8.0.0
119-
120-
Version 7.0.0 introduced ApiVersion, and known versions were hardcoded into the gem. Manually defining API versions is no longer required for versions not listed in the gem. Version 8.0.0 removes the following:
121-
* `ShopifyAPI::ApiVersion::Unstable`
122-
* `ShopifyAPI::ApiVersion::Release`
123-
* `ShopifyAPI::ApiVersion.define_version`
124-
125-
The following methods on `ApiVersion` have been deprecated:
126-
- `.coerce_to_version` deprecated. use `.find_version`
127-
- `.define_known_versions` deprecated. Use `.fetch_known_versions`
128-
- `.clear_defined_versions` deprecated. Use. `.clear_known_versions`
129-
- `.latest_stable_version` deprecated. Use `ShopifyAPI::Meta.admin_versions.find(&:latest_supported)` (this fetches info from Shopify servers. No authentication required.)
130-
- `#name` deprecated. Use `#handle`
131-
- `#stable?` deprecated. Use `#supported?`
132-
133-
Version 8.0.0 introduces a _version lookup mode_. By default, `ShopifyAPI::ApiVersion.version_lookup_mode` is `:define_on_unknown`. When setting the api_version on `Session` or `Base`, the `api_version` attribute takes a version handle (i.e. `'2019-07'` or `:unstable`) and sets an instance of `ShopifyAPI::ApiVersion` matching the handle. When the version_lookup_mode is set to `:define_on_unknown`, any handle will naïvely create a new `ApiVersion` if the version is not in the known versions returned by `ShopifyAPI::ApiVersion.versions`.
134-
135-
To ensure you're setting only known and active versions, call :
136-
137-
```ruby
138-
ShopifyAPI::ApiVersion.version_lookup_mode = :raise_on_unknown
139-
ShopifyAPI::ApiVersion.fetch_known_versions
140-
```
141-
142-
Known and active versions are fetched from https://app.shopify.com/services/apis.json and cached. Trying to use a version outside this cached set will raise an error. To switch back to naïve lookup and create a version if one is not found, call `ShopifyAPI::ApiVersion.version_lookup_mode = :define_on_unknown`.
143-
144-
### Breaking change notice for version 7.0.0
145-
146-
#### Changes to ShopifyAPI::Session
147-
When creating sessions, `api_version`is now required and uses keyword arguments.
148-
149-
To upgrade your use of ShopifyAPI you will need to make the following changes.
150-
151-
```ruby
152-
ShopifyAPI::Session.new(domain, token, extras)
153-
```
154-
is now
155-
```ruby
156-
ShopifyAPI::Session.new(domain: domain, token: token, api_version: api_version, extras: extras)
157-
```
158-
Note `extras` is still optional. The other arguments are required.
159-
160-
```ruby
161-
ShopifyAPI::Session.temp(domain, token, extras) do
162-
...
163-
end
164-
```
165-
is now
166-
```ruby
167-
ShopifyAPI::Session.temp(domain: domain, token: token, api_version: api_version) do
168-
...
169-
end
170-
```
171-
172-
For example, if you want to use the `2019-04` version, you will create a session like this:
173-
```ruby
174-
session = ShopifyAPI::Session.new(domain: domain, token: token, api_version: '2019-04')
175-
```
176-
if you want to use the `unstable` version, you will create a session like this:
177-
```ruby
178-
session = ShopifyAPI::Session.new(domain: domain, token: token, api_version: :unstable)
179-
```
180-
181-
#### Changes to how to define resources
182-
183-
If you have defined or customized Resources, classes that extend `ShopifyAPI::Base`:
184-
The use of `self.prefix =` has been deprecated; you should now use `self.resource =` and not include `/admin`.
185-
For example, if you specified a prefix like this before:
186-
```ruby
187-
class MyResource < ShopifyAPI::Base
188-
self.prefix = '/admin/shop/'
189-
end
190-
```
191-
You will update this to:
192-
```ruby
193-
class MyResource < ShopifyAPI::Base
194-
self.resource_prefix = 'shop/'
195-
end
196-
```
197-
198-
#### URL construction
199-
200-
If you have specified any full paths for API calls in find
201-
```ruby
202-
def self.current(options={})
203-
find(:one, options.merge(from: "/admin/shop.#{format.extension}"))
204-
end
205-
```
206-
would be changed to
207-
208-
```ruby
209-
def self.current(options = {})
210-
find(:one, options.merge(
211-
from: api_version.construct_api_path("shop.#{format.extension}")
212-
))
213-
end
214-
```
215-
216-
#### URLs that have not changed
217-
218-
- OAuth URLs for `authorize`, getting the `access_token` from a code, `access_scopes`, and using a `refresh_token` have _not_ changed.
219-
- get: `/admin/oauth/authorize`
220-
- post: `/admin/oauth/access_token`
221-
- get: `/admin/oauth/access_scopes`
222-
- URLs for the merchant’s web admin have _not_ changed. For example: to send the merchant to the product page the url is still `/admin/product/<id>`
118+
## Breaking changes for older versions
223119

120+
See [BREAKING_CHANGES_FOR_OLDER_VERSIONS](BREAKING_CHANGES_FOR_OLDER_VERSIONS.md)
224121

225122
## Developing this gem
226123

0 commit comments

Comments
 (0)