Skip to content

Commit c4e6ea7

Browse files
authored
Update Slack Web API (#455)
* Update Slack Web API * Update `CHANGELOG.md` * Update CHANGELOG.md
1 parent 040a9be commit c4e6ea7

File tree

10 files changed

+289
-34
lines changed

10 files changed

+289
-34
lines changed

CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
### 2.2.0 (Next)
22

33
* Your contribution here.
4+
* [#455](https://github.com/slack-ruby/slack-ruby-client/pull/455): Update Slack API: Added pagination to `team.accessLogs` and `AppsDatastore` methods - [@marfoldi](https://github.com/marfoldi).
45
* [#454](https://github.com/slack-ruby/slack-ruby-client/pull/454): Added `Slack::Messages::Formatting#escape` - [@marfoldi](https://github.com/marfoldi).
56
* [#452](https://github.com/slack-ruby/slack-ruby-client/pull/452): Automatically generate Web API multi-argument requirements from docs - [@jmanian](https://github.com/jmanian).
67
* [#448](https://github.com/slack-ruby/slack-ruby-client/pull/448), [#453](https://github.com/slack-ruby/slack-ruby-client/pull/453): Automatically convert more Web API arguments to JSON-encoded strings - [@jmanian](https://github.com/jmanian).

CONTRIBUTING.md

Lines changed: 35 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -63,38 +63,6 @@ Ruby style is enforced with [Rubocop](https://github.com/bbatsov/rubocop). Run `
6363

6464
Make sure that `bundle exec rake` completes without errors.
6565

66-
### Update Slack Web API
67-
68-
Slack Web API is updated from https://github.com/slack-ruby/slack-api-ref, a maintained, machine-readable version of Slack API Docs, generated by scraping [api.slack.com](https://api.slack.com). To update the Web API from the latest definition run the following Rake task.
69-
70-
```
71-
bundle exec rake slack:api:update
72-
```
73-
74-
#### Patching Slack Web API
75-
76-
Sometimes it's necessary to patch auto-generated Slack Web API methods. For example, we want to help clients with calling `to_json` on the `attachments` parameter sent to `chat_postMessage`. See [#20](https://github.com/slack-ruby/slack-ruby-client/issues/20).
77-
78-
The broad steps are:
79-
1. Run `rake slack:api:update` to check that existing patches are still valid.
80-
- If you run into a `failed to apply patch` error, the auto-generated methods likely drifted from the last patch. Follow the steps [below](#resolving-patch-errors).
81-
- This may add new methods if the API has updated, please split them up into multiple PRs if so.
82-
2. Make a change to a generated file, for example `lib/slack/web/api/endpoints/chat.rb`.
83-
3. Generate a patch:
84-
```
85-
git diff --no-color HEAD lib/slack/web/api/endpoints/chat.rb > lib/slack/web/api/patches/chat.added-support.patch
86-
```
87-
4. Run `rake slack:api:update` to ensure that the patch is cleanly applied. Implement a test for the added or modified functionality and commit the patch file.
88-
89-
##### Resolving Patch Errors
90-
91-
The auto-generated method files may drift overtime e.g. new arguments may be added or descriptions changed. Since previous patches were based on the older auto-generated files, git may be unable to apply them to the new files. Resolving them requires some good ol' splicing:
92-
1. Run `rake slack:api:update SKIP_PATCH=true` to create the raw auto-generated files. Commit the files that you are updating, so we can run `git diff` later.
93-
2. Go through the old patches for the files (e.g. in `lib/slack/web/api/patches/chat.added-support.patch`), copying code into the new files.
94-
- Run `git apply --reject path/to/patch-file.patch` to see hunks that couldn't be applied.
95-
3. Continue with Step 2 [above](#patching-slack-web-api).
96-
97-
9866
### Write Documentation
9967

10068
Document any external behavior in the [README](README.md).
@@ -163,6 +131,41 @@ Go back to your pull request after a few minutes and see whether it passed muste
163131
### Be Patient
164132

165133
It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
134+
While you wait you can help with keeping the Slack Web API up to date, see [below](#update-slack-web-api).
135+
136+
### Update Slack Web API
137+
138+
Please make sure to [create a separate branch](#create-a-topic-branch) for your changes.
139+
140+
Slack Web API is updated from https://github.com/slack-ruby/slack-api-ref, a maintained, machine-readable version of Slack API Docs, generated by scraping [api.slack.com](https://api.slack.com). To update the Web API from the latest definition run the following Rake task.
141+
142+
```
143+
bundle exec rake slack:api:update
144+
```
145+
146+
#### Patching Slack Web API
147+
148+
Sometimes it's necessary to patch auto-generated Slack Web API methods. For example, we want to help clients with calling `to_json` on the `attachments` parameter sent to `chat_postMessage`. See [#20](https://github.com/slack-ruby/slack-ruby-client/issues/20).
149+
150+
The broad steps are:
151+
1. Run `rake slack:api:update` to check that existing patches are still valid.
152+
- If you run into a `failed to apply patch` error, the auto-generated methods likely drifted from the last patch. Follow the steps [below](#resolving-patch-errors).
153+
- This may add new methods if the API has updated, please split them up into multiple PRs if so.
154+
2. Make a change to a generated file, for example `lib/slack/web/api/endpoints/chat.rb`.
155+
3. Generate a patch:
156+
```
157+
git diff --no-color HEAD lib/slack/web/api/endpoints/chat.rb > lib/slack/web/api/patches/chat.added-support.patch
158+
```
159+
4. Run `rake slack:api:update` to ensure that the patch is cleanly applied. Implement a test for the added or modified functionality and commit the patch file.
160+
161+
##### Resolving Patch Errors
162+
163+
The auto-generated method files may drift overtime e.g. new arguments may be added or descriptions changed. Since previous patches were based on the older auto-generated files, git may be unable to apply them to the new files. Resolving them requires some good ol' splicing:
164+
1. Run `rake slack:api:update SKIP_PATCH=true` to create the raw auto-generated files. Commit the files that you are updating, so we can run `git diff` later.
165+
2. Go through the old patches for the files (e.g. in `lib/slack/web/api/patches/chat.added-support.patch`), copying code into the new files.
166+
- Run `git apply --reject path/to/patch-file.patch` to see hunks that couldn't be applied.
167+
3. Continue with Step 2 [above](#patching-slack-web-api).
168+
166169
167170
## Thank You
168171

bin/commands/apps_datastore.rb

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# frozen_string_literal: true
2+
# This file was auto-generated by lib/tasks/web.rake
3+
4+
module Slack
5+
module Cli
6+
class App
7+
desc 'AppsDatastore methods.'
8+
command 'apps_datastore' do |g|
9+
g.desc 'Delete an item from a datastore'
10+
g.long_desc %( Delete an item from a datastore )
11+
g.command 'delete' do |c|
12+
c.flag 'datastore', desc: 'name of the datastore.'
13+
c.flag 'id', desc: 'item id.'
14+
c.flag 'app_id', desc: '.'
15+
c.action do |_global_options, options, _args|
16+
puts JSON.dump(@client.apps_datastore_delete(options))
17+
end
18+
end
19+
20+
g.desc 'Get an item from a datastore'
21+
g.long_desc %( Get an item from a datastore )
22+
g.command 'get' do |c|
23+
c.flag 'datastore', desc: 'name of the datastore.'
24+
c.flag 'id', desc: 'item id.'
25+
c.flag 'app_id', desc: '.'
26+
c.action do |_global_options, options, _args|
27+
puts JSON.dump(@client.apps_datastore_get(options))
28+
end
29+
end
30+
31+
g.desc 'Creates a new item, or replaces an old item with a new item.'
32+
g.long_desc %( Creates a new item, or replaces an old item with a new item. )
33+
g.command 'put' do |c|
34+
c.flag 'datastore', desc: 'name of the datastore.'
35+
c.flag 'item', desc: 'attribute names and values of the item.'
36+
c.flag 'app_id', desc: '.'
37+
c.action do |_global_options, options, _args|
38+
puts JSON.dump(@client.apps_datastore_put(options))
39+
end
40+
end
41+
42+
g.desc 'Query a datastore for items'
43+
g.long_desc %( Query a datastore for items )
44+
g.command 'query' do |c|
45+
c.flag 'datastore', desc: 'Name of the datastore.'
46+
c.flag 'app_id', desc: 'Required if calling with user token.'
47+
c.flag 'cursor', desc: 'Set cursor to next_cursor returned by the previous call to list items in the next page.'
48+
c.flag 'expression', desc: 'A query filter expression https://api.slack.com/future/datastores.'
49+
c.flag 'expression_attributes', desc: 'A map of attributes referenced in expression.'
50+
c.flag 'expression_values', desc: 'A map of values referenced in expression.'
51+
c.flag 'limit', desc: 'The maximum number of items to evaluate for a given request (not necessarily the number of matching items). If the given request dataset size exceeds 1 MB before reaching the limit, the returned item count will likely be less than the limit. In any case where there are more items available beyond an imposed limit, a next_cursor value will be provided for use in subsequent requests.'
52+
c.action do |_global_options, options, _args|
53+
puts JSON.dump(@client.apps_datastore_query(options))
54+
end
55+
end
56+
57+
g.desc "Edits an existing item's attributes, or adds a new item if it does not already exist."
58+
g.long_desc %( Edits an existing item's attributes, or adds a new item if it does not already exist. )
59+
g.command 'update' do |c|
60+
c.flag 'datastore', desc: 'name of the datastore.'
61+
c.flag 'item', desc: 'attribute names and values to be updated.'
62+
c.flag 'app_id', desc: '.'
63+
c.action do |_global_options, options, _args|
64+
puts JSON.dump(@client.apps_datastore_update(options))
65+
end
66+
end
67+
end
68+
end
69+
end
70+
end

bin/commands/team.rb

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ class App
1010
g.long_desc %( Gets the access logs for the current team. )
1111
g.command 'accessLogs' do |c|
1212
c.flag 'before', desc: 'End of time range of logs to include in results (inclusive).'
13+
c.flag 'cursor', desc: "Parameter for pagination. Set cursor equal to the next_cursor attribute returned by the previous request's response_metadata. This parameter is optional, but pagination is mandatory: the default value simply fetches the first 'page' of the collection. See pagination for more details."
14+
c.flag 'limit', desc: "The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the list hasn't been reached. If specified, result is returned using a cursor-based approach instead of a classic one."
1315
c.flag 'team_id', desc: 'encoded team id to get logs from, required if org token is used.'
1416
c.action do |_global_options, options, _args|
1517
puts JSON.dump(@client.team_accessLogs(options))

lib/slack/web/api/endpoints.rb

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
require_relative 'endpoints/api'
2929
require_relative 'endpoints/apps'
3030
require_relative 'endpoints/apps_connections'
31+
require_relative 'endpoints/apps_datastore'
3132
require_relative 'endpoints/apps_event_authorizations'
3233
require_relative 'endpoints/apps_manifest'
3334
require_relative 'endpoints/auth'
@@ -105,6 +106,7 @@ module Endpoints
105106
include Api
106107
include Apps
107108
include AppsConnections
109+
include AppsDatastore
108110
include AppsEventAuthorizations
109111
include AppsManifest
110112
include Auth
Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# frozen_string_literal: true
2+
# This file was auto-generated by lib/tasks/web.rake
3+
4+
module Slack
5+
module Web
6+
module Api
7+
module Endpoints
8+
module AppsDatastore
9+
#
10+
# Delete an item from a datastore
11+
#
12+
# @option options [string] :datastore
13+
# name of the datastore.
14+
# @option options [string] :id
15+
# item id.
16+
# @option options [Object] :app_id
17+
# .
18+
# @see https://api.slack.com/methods/apps.datastore.delete
19+
# @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/apps.datastore/apps.datastore.delete.json
20+
def apps_datastore_delete(options = {})
21+
raise ArgumentError, 'Required arguments :datastore missing' if options[:datastore].nil?
22+
raise ArgumentError, 'Required arguments :id missing' if options[:id].nil?
23+
post('apps.datastore.delete', options)
24+
end
25+
26+
#
27+
# Get an item from a datastore
28+
#
29+
# @option options [string] :datastore
30+
# name of the datastore.
31+
# @option options [string] :id
32+
# item id.
33+
# @option options [Object] :app_id
34+
# .
35+
# @see https://api.slack.com/methods/apps.datastore.get
36+
# @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/apps.datastore/apps.datastore.get.json
37+
def apps_datastore_get(options = {})
38+
raise ArgumentError, 'Required arguments :datastore missing' if options[:datastore].nil?
39+
raise ArgumentError, 'Required arguments :id missing' if options[:id].nil?
40+
post('apps.datastore.get', options)
41+
end
42+
43+
#
44+
# Creates a new item, or replaces an old item with a new item.
45+
#
46+
# @option options [string] :datastore
47+
# name of the datastore.
48+
# @option options [object] :item
49+
# attribute names and values of the item.
50+
# @option options [Object] :app_id
51+
# .
52+
# @see https://api.slack.com/methods/apps.datastore.put
53+
# @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/apps.datastore/apps.datastore.put.json
54+
def apps_datastore_put(options = {})
55+
raise ArgumentError, 'Required arguments :datastore missing' if options[:datastore].nil?
56+
raise ArgumentError, 'Required arguments :item missing' if options[:item].nil?
57+
post('apps.datastore.put', options)
58+
end
59+
60+
#
61+
# Query a datastore for items
62+
#
63+
# @option options [string] :datastore
64+
# Name of the datastore.
65+
# @option options [Object] :app_id
66+
# Required if calling with user token.
67+
# @option options [string] :cursor
68+
# Set cursor to next_cursor returned by the previous call to list items in the next page.
69+
# @option options [string] :expression
70+
# A query filter expression https://api.slack.com/future/datastores.
71+
# @option options [object] :expression_attributes
72+
# A map of attributes referenced in expression.
73+
# @option options [object] :expression_values
74+
# A map of values referenced in expression.
75+
# @option options [integer] :limit
76+
# The maximum number of items to evaluate for a given request (not necessarily the number of matching items). If the given request dataset size exceeds 1 MB before reaching the limit, the returned item count will likely be less than the limit. In any case where there are more items available beyond an imposed limit, a next_cursor value will be provided for use in subsequent requests.
77+
# @see https://api.slack.com/methods/apps.datastore.query
78+
# @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/apps.datastore/apps.datastore.query.json
79+
def apps_datastore_query(options = {})
80+
raise ArgumentError, 'Required arguments :datastore missing' if options[:datastore].nil?
81+
if block_given?
82+
Pagination::Cursor.new(self, :apps_datastore_query, options).each do |page|
83+
yield page
84+
end
85+
else
86+
post('apps.datastore.query', options)
87+
end
88+
end
89+
90+
#
91+
# Edits an existing item's attributes, or adds a new item if it does not already exist.
92+
#
93+
# @option options [string] :datastore
94+
# name of the datastore.
95+
# @option options [object] :item
96+
# attribute names and values to be updated.
97+
# @option options [Object] :app_id
98+
# .
99+
# @see https://api.slack.com/methods/apps.datastore.update
100+
# @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/apps.datastore/apps.datastore.update.json
101+
def apps_datastore_update(options = {})
102+
raise ArgumentError, 'Required arguments :datastore missing' if options[:datastore].nil?
103+
raise ArgumentError, 'Required arguments :item missing' if options[:item].nil?
104+
post('apps.datastore.update', options)
105+
end
106+
end
107+
end
108+
end
109+
end
110+
end

lib/slack/web/api/endpoints/team.rb

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,22 @@ module Team
1111
#
1212
# @option options [string] :before
1313
# End of time range of logs to include in results (inclusive).
14+
# @option options [string] :cursor
15+
# Parameter for pagination. Set cursor equal to the next_cursor attribute returned by the previous request's response_metadata. This parameter is optional, but pagination is mandatory: the default value simply fetches the first "page" of the collection. See pagination for more details.
16+
# @option options [integer] :limit
17+
# The maximum number of items to return. Fewer than the requested number of items may be returned, even if the end of the list hasn't been reached. If specified, result is returned using a cursor-based approach instead of a classic one.
1418
# @option options [string] :team_id
1519
# encoded team id to get logs from, required if org token is used.
1620
# @see https://api.slack.com/methods/team.accessLogs
1721
# @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/team/team.accessLogs.json
1822
def team_accessLogs(options = {})
19-
post('team.accessLogs', options)
23+
if block_given?
24+
Pagination::Cursor.new(self, :team_accessLogs, options).each do |page|
25+
yield page
26+
end
27+
else
28+
post('team.accessLogs', options)
29+
end
2030
end
2131

2232
#

0 commit comments

Comments
 (0)