mycorrhiza
mycorrhiza copied to clipboard
bouncepaw
JSON HTTP API
Currently, Mycorrhiza does not have an API designed for machines. Most routes are meant to be requested by humans through browsers. Even though we can make third-party programs request them, they still cannot get all of the information they may need, so we need an API.
An example of a route designed for machines: https://mycorrhiza.wiki/title-search-json/?q=u
Why JSON? Because this format is:
- Simple enough to put up with
- The most popular format for this task in the industry
- Already used in Mycorrhiza
So, no GraphQL nor XML. No home-brew serialization format (even though the idea is compelling).
A schema might be good too: https://json-schema.org
How do we make it good? Dunno, never done that.
Here are the routes I want to provide for the API:
-
/mycorrhizatells what version of Mycorrhiza used and stuff like that. - All of human-oriented routes should be copied. Any exceptions?
I've seen many services include API version in the route. I don't want to do this.
By the way, such an API will make alternative front-ends possible. Cool.
To be honest, GraphQL is much more robust and efficient. Not sure why would anyone prefer simple REST APIs.
not sure why would anyone prefer simple REST APIs.
Because it is
simple
as you may generate the output without any dependencies, and it would work.
I'd propose using /api or /json base route and /<api/json>/about instead of /mycorrhiza, though.
as you may generate the output without any dependencies, and it would work.
What do you mean "without dependencies"? What dependencies do you need to make a single POST request?
What do you mean "without dependencies"?
I literally mean that Mycorrhiza generates JSON output from a template file. Cheap, easy, just working.
What dependencies do you need to make a single POST request?
If you don't need to provide JSON data as an input, it's nothing above we already have. If you do need, encoding/json is out-of-the-box, AFAIK. GraphQL, on the other hand, does require at least graphql-go, if not more.
I literally mean that Mycorrhiza generates JSON output from a template file. Cheap, easy, just working.
What the fuck why would you use templates for generating JSON responses, encoding/json is already used everywhere and GraphQL responses are encoded as JSON too
If you don't need to provide JSON data as an input, it's nothing above we already have. If you do need,
encoding/jsonis out-of-the-box, AFAIK. GraphQL, on the other hand, does require at leastgraphql-go, if not more.
That's, like, an encoding library every proper language has?
Stop butthurting, please. At least we have a kind of common ground that we should change existing JSON API to utilize encoding/json. Sure, it is nearly standard, so why not.
The point which started the discussion is usage of more complex API, like GraphQL. My opinion is that plain JSON API complies the project's philosophy of sm0lness, nothing more, nothing less.