search

slack-ruby / slack-api-ref

This is a maintained, machine-readable version of the Slack API Docs.
MIT License
42 stars 15 forks source link

Has https://api.slack.com/methods changed? #47

Closed dblock closed 2 years ago

dblock commented 2 years ago

Cron hasn't made any updates. Has https://api.slack.com/methods changed?

chrisbloom7 commented 2 years ago

@dblock what is the purpose of groups? I see it currently only contains undocumented groups - should it contain all group info?

chrisbloom7 commented 2 years ago

Yup, the HTML for these pages have definitely changed. So far my research into this has turned up good news and bad news:

Good news: Both the events and methods pages include some JSON we can parse to get a list of items on the page, making that part a little easier.

Bad news: Figuring out deprecation info looks to be more difficult.

I propose we simply use the flag from the JSON data and skip adding any deprecation text or alternative methods. Is that acceptable?

dblock commented 2 years ago

Bad news: Figuring out deprecation info looks to be more difficult.

That's why we pay you the big bucks ;)

  • Some deprecated methods simply redirect to their replacements, for instance im.list -> conversations.list. The JSON data includes a flag saying these methods are deprecated, but there's no way to use scrape_deprecation to get any additional info.

That's fine, we can just delete that. These methods are now "fully deprecated" vs. "will be deprecated in the future", and we should be removing them from the client, too.

  • Some methods are not marked as deprecated in the JSON, but say they are deprecated in their description. For instance, users.setActive says so in it's description but has no other info on the method page, while rtm.start says so in it's description and has a warning alert that says DEPRECATED with a link to more info and includes an error rtm_connect_required and a warning method_deprecated that include additional info. There doesn't seem to be any consistency here.

Do these consistently return a method_deprecated error?

I propose we simply use the flag from the JSON data and skip adding any deprecation text or alternative methods. Is that acceptable?

Yes.

dblock commented 2 years ago

@dblock what is the purpose of groups? I see it currently only contains undocumented groups - should it contain all group info?

That used to have a bunch of other things, like admin functions. An auto update removed that in https://github.com/slack-ruby/slack-api-ref/commit/62c00d02381c88178c7529fe5f806fbfcea31871#diff-4ed379d418bb86290a01117e9ceb0debffc4d1b7087db6c04882fbc4e50132f4, so I think once you fix the parser we will start seeing things here again.

chrisbloom7 commented 2 years ago

Do these consistently return a method_deprecated error?

That's unclear without some probing tests, but I don't think so. I think the method_deprecated error shows up in every method as a possible error message. For example, even https://api.slack.com/methods/users.info includes it as a possible error message a user might receive when making that request.

Also, OMG, they just published a new docs layout as I was midway through testing a new set of spiders... 🤦🏻

chrisbloom7 commented 2 years ago

Was https://github.com/slack-ruby/slack-api-ref/blob/master/tasks/lib/slack_api/methods_spider.rb#L116-L129 intended to massage types to something more relevant to the library, or was this data missing in a previous version of the docs and we had to guess? It's explicitly available now, so wondering if I should still run each argument through that method or if I can just use what is provided.

For reference, here's a list of explicitly defined types:

'' # An empty type value
array
channel
manifest object as string
object
string
user
boolean
bot
integer
team
number
blocks[] as string
null # this is the actual value 'null' 🤷