API contract

[Baccata]

Hi there,

I maintain a vscode plugin that leverages the Scaladex API. Unfortunately, it recently stopped working (I noticed today but I'm not sure how long it's been the case), and I presume it may be due to a change (or deletion) of an api endpoint I was relying on. I'm thinking this one.

I'm failing to find the sourcecode containing the implementation of this endpoint I was hitting. I supposed it's changed a while ago and a recent redeployment may have broken my integration. What's weird is that hitting the endpoint doesn't give me a 404, but a timeout.

Generally speaking, I'd greatly appreciate if you could provide (and advertise) an API contract and verify your API against it as part of your tests. The contract could be expressed in different ways. OpenAPI is pretty common, and there exist a pretty decent Scala code generator for it. I can also recommend Smithy, for which I maintain Scala code generator under the DisneyStreaming organisation, with opt-in http4s integration. I'm not necessarily suggesting that you use either for the implementation of the API, but rather within your tests, to guarantee that the implementation is up-to-date with the contract.

Having an API contract would greatly facilitate the writing of third party tools like the vscode plugin I maintain, and would reduce the risk of accidental breakage in the future.

In the meantime, could you suggest an endpoint I could hit such that, provided a github organisation and project combo, I could retrieve the list of the artifacts ?

Thank you in advance.

[adpi2]

Thanks @Baccata for opening this discussion. This is a long standing issue and I hope I will be able to solve it soon, probably not before the end of the year though.

The problem is that we have two distinct APIs the programmatic one and the pages. Once, they probably were the same but they completely diverged. The programmatic API is not tested, not documented so it is really hard to maintain it. Of course we could test and document it and maintain it forever. But it is kind of annoying to maintain something that is completely outdated. I am not saying that it is fine to break it though.

I would rather put my effort on introducing a new API that is by design the same as the pages. Same parameters, same data in the output. It would be tested and documented (API contract) and we would maintain the forward compatibility. We could also publish it as a library.

Coming back to your problem about the endpoint not working. The problem was that our server crashed, for a not-yet-known reason. It should work now: https://index.scala-lang.org/api/project?organization=typelevel&repository=cats

[Baccata]

Thanks for the answer :) good to know it's working again 😄

The plan sounds reasonable, I'll be happy to change my integration against a new API when you (Scaladex maintainers) get around to designing/implementing it 👍

I'd appreciate a ping when that's the case, if you remember 😄

[adpi2]

Here is a description of the API I would like to implement, with a clear and stable contract: #1482

Feel free to review it and comment.

[adpi2]

I deployed it from #1484