slack-api-ref

slack-api-ref copied to clipboard

The sample responses from the official Slack documentation are often invalid JSON. For example, check files.upload (because of '...') or im.history (because of a trailing comma in the second message).

Given that slackhq/slack-api-docs is currently not receiving any updates, we should fix that on our side.

I was looking into possible solutions. Unfortunately I did not find any pure-Ruby solution yet. Do you know of any? JSON is tricky to fix automatically. The two most promising solutions I found are:

• OWASP/json-sanitizer
• eslint/eslint

Both projects promise automatic fixing of JSON. Since eslint/eslint is well-maintained and offers lots of fixes, I would go with that.

Heads up:

• Javascript Runtime required.
• eslint fixes files in-place. We would need to call it from the commandline.

Here is an example of how I would integrate it. I'm not really happy about the code but I couldn't come up with anything better either.

If you like the idea then I would go ahead and integrate it. Otherwise I'm open for suggestions.

Tested eslint and it would fix the trailing commas.

Alternatively we could write a simple Ruby class which fixes only the errors that we encounter during parsing. Namely:

• trailing commas
• unquoted strings (e.g. '...')

Advantages:

• Simple
• Pure Ruby
• Easy to integrate

Disadvantages:

• will not cover other issues

Really slack should fix those, I do suggest opening at least a ticket.

In the meantime since it's a hack I would use whatever.

Btw, @mre work on your fork, don't create branches here and cleanup the merged ones? This way we keep this repo clean.

Just wanted to add some feedback about my attempts to fix this issue. I've tried to fix the JSON syntax errors with eslint, but there are just too many different error cases. I also tried to add some simple heuristics (basically applying some regular expressions before running eslint), but as expected that made things even more fragile. As of now I don't see an easy way to make this happen. If anybody else wants to give it a shot, I'd be more than happy to brainstorm on ideas. It would be really great to have this, as it would bring me one step closer towards a fully auto-generated Slack client for Rust.

Maybe opening issues with Slack and asking them to provide working examples? Or providing alternate hand-written working examples here that overwrite the worst ones?

Thanks @dblock, I could add hand-written examples but I could not keep them up-to-date, so that's why I didn't do it. I've added a comment to the issue referenced above. Let's see. 👍

There is a comment here from a Slack team member regarding fixing im.history https://github.com/slackhq/slack-api-docs/issues/74#issuecomment-334281728 and the examples I checked from https://github.com/slackhq/slack-api-docs/issues/73 are now valid JSON.