Add machine-readable API schema #3235
-
If you need to interact with Discord API you (or other people which libraries you use) have to manually write code for every type and method Discord has. Since this is just an utility and not a task which you normally trying to achieve it should be as easy as possible. Thus, consider adding some sort of generated specs that can be used to make tools for generating all kinds of wrappers. Like openapi/swagger or json schema like Slack and Microsoft do. |
Beta Was this translation helpful? Give feedback.
Replies: 16 comments 10 replies
-
I’ll be brutally honest, I am quite disappointed to discover that a service so popular that goes out of its encourage developers to integrate, embed, and build on top of their api, lacks any machine readable API specification for developers. Really, really disappointed Edit: This shouldn't be funny. How is the discord public api developers lack of respect for the developers who use their api funny? Standards based api specifications makes it easier for everyone to work with their API. Their API documentation isn’t translated, they have no machine readable API specification to make up for the lack of translated documentation for people who speak languages other than English. I am disappointed because this is at odds with their professed goals of being for everyone. Apparently they are only for everyone if you’re a user/customer. Developers better read English and have enough spare time to implement their api from scratch... And before someone mentions their community libraries, I’d argue that being required to use those to get anything practical done, because the official API isn’t specified well enough to just use directly with standard tools, is just a further disappointment. |
Beta Was this translation helpful? Give feedback.
-
as someone who is working on literally reading api paths out of the markdown all i can say is YES PLEASE |
Beta Was this translation helpful? Give feedback.
-
I totally agree, |
Beta Was this translation helpful? Give feedback.
-
Chiming in with a +1. The endpoints should be defined in some structured manner that the docs are then generated out of. |
Beta Was this translation helpful? Give feedback.
-
+1 - having an OpenAPI spec would be amazing. |
Beta Was this translation helpful? Give feedback.
-
+1, literally any spec would be amazing and would mean I can finally retire my hacky docs-parsing tool. |
Beta Was this translation helpful? Give feedback.
-
I use something like a schema in my library. Here's an example: There are some issues tho, lazy parsing is required for some of Discord's structures like the gateway payload and slash command values. These require that parts of the json to be parsed first before you know the type of some values. I don't use any standardized json schema, but to define all the types, there needs to be some generics or placeholder type specifiers or some way to handle types that can be one of many. |
Beta Was this translation helpful? Give feedback.
-
This would be great but I don't feel like this is the highest thing that they should probably prioritize as of now |
Beta Was this translation helpful? Give feedback.
-
We are attempting to do that here: https://github.com/switchupcb/discord-api-spec However, it would be way easier for Discord to provide this from their source (as discussed above). |
Beta Was this translation helpful? Give feedback.
-
We ended up archiving the specification attempt by JSON and simply implemented the Go Types at https://github.com/switchupcb/dasgo. These types are pulled from a generator (such as one implemented in https://github.com/switchupcb/disgo) which makes maintaining the thousands of lines of code super simple. |
Beta Was this translation helpful? Give feedback.
-
Jup, adding my plus one as well. The only options right now are API implementations with random dependencies or weird implementations. Just generating your own types/api calls is way nicer and more elegant imho. Can't believe I'm saying this, but it was easier with webservices with WSDL back in the day... |
Beta Was this translation helpful? Give feedback.
-
+1 for a standard OpenAPI spec. Super helpful for client generation and writing test mocks. |
Beta Was this translation helpful? Give feedback.
-
So I just finished an attempt to make an OpenAPI spec for discord, you can check it here: https://github.com/hugoattal/discord-openapi YAML file: https://raw.githubusercontent.com/hugoattal/discord-openapi/main/src/output/openapi.yaml You can check it out with the swagger UI: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/hugoattal/discord-openapi/main/src/output/openapi.yaml |
Beta Was this translation helpful? Give feedback.
-
Discord also announced an upcoming OpenAPI Specification a few months ago. |
Beta Was this translation helpful? Give feedback.
-
We've published a preview of OpenAPI Spec 3.1 for Discord HTTP API https://github.com/discord/discord-api-spec 🎉 |
Beta Was this translation helpful? Give feedback.
We've published a preview of OpenAPI Spec 3.1 for Discord HTTP API https://github.com/discord/discord-api-spec 🎉