Site Home / Forum / Developers / OpenAPI / Swagger Compliant API
OpenAPI / Swagger Compliant API
Posted: 17 Apr 2021 08:52
IronManRust Posts: 2 Joined: 2021-04-17
First off, I want to say I greatly appreciate what the community has put together here. I recently discovered this site and integrated it into a little hobby project I've been working on:
While I fully acknowledge how much work keeping the infrastructure and code base of something like this running entails, especially on a volunteer or Patreon-backed basis, I was wondering if the topic of a standards-compliant, v2 API has ever come up? Specifically, something that conforms to the OpenAPI (aka Swagger) specification:
https://swagger.io/specification/
It appears that the current API tooling is PHP-based, given I see "x-powered-by PHP/7.4.1" in the API response headers. I'm a .NET and Node developer, so I can't speak to the state of the PHP-based OpenAPI libraries, but if you were able to put out something standards-compliant, it would open up a lot of value for your consumers.
With a compliant OpenAPI schema, you could publish SDKs in dozens of languages with almost no work on your part:
There are also multiple documentation generators available, outputting both HTML and downloadable artifacts like PDFs.
Anyway, I hope this post doesn't come off as presumptions on my part. It very well could be that the admins are fully aware of this tooling and there just isn't the business case or bandwidth to implement them. And that's totally fine, and a valid decision. I just have a passion for APIs - I work on them quite a bit in my day job - and love to see good ideas reach their full potential.
👍 zag
Posted: 17 Apr 2021 12:16
zag Posts: 228 Joined: 2020-07-14
Sounds good to me! We are definitely due a V2 of the API.
I will start to do some research.
Posted: 17 Apr 2021 17:43
IronManRust Posts: 2 Joined: 2021-04-17
Sounds good. A couple other suggestions if you're looking to re-do your API contract:
1) The API key and request/response formats should really be headers, and the routes should represent resources and not actions, REST-style:
GET /api/v2/artist?name=nirvana
-H "accept: application/json"
-H "apikey: abc123"
GET /api/v2/song?artist=nirvana&name=lithium
-H "accept: application/json"
-H "apikey: abc123"
2) The variable type prefixes are probably unnecessary (strArtist vs. artist, intFormedYear vs. yearFormed, etc.) since you can express the data types as part of the OpenAPI spec.
3) Instead of including every translated string in every response, consider accepting a language header on every request:
4) Consider including hypermedia links with every response, so the user knows how to navigate through your API implicitly. As an example, if they search for an artist resource, there should be a collection of links to that artist's albums. Here's an overview of that concept:
https://restfulapi.net/hateoas/
In general, written documentation of how to navigate an API should be unnecessary. The root call of your API (i.e. /api/v2) should return nothing but a collection of top-level resources (i.e. artist, etc.) and then a user should be able to naturally navigate from there.
