With Ore API V2 right around the corner, we’re now considering our plans to deprecate the old API. While we want to remove the old API as soon as possible, we also want to make sure that we don’t break stuff when doing so. That being said though, from the day API V2 is released as stable, we will no longer offer any support for API V1. If something breaks in it, either because of a bug or because we don’t support that thing anymore, it will stay broken. Channels are a prime example here, but other examples might be not returning the correct data, like saying that a project has 0 stars when it really has 50. If you want a fixed API, move to V2. For removing endpoints though, we’ll do it in batches. We’ll start with removing the ones that shouldn’t be used, or we believe aren’t used much at all, and save the important ones for later.
Unversioned endpoints and authenticated endpoints will be the first to be removed. We will remove them in the same release that includes API V2. Unversioned endpoints have been deprecated for over a year now, and if people haven’t migrated yet, then we don’t know how long they will take to do so. Authenticated endpoints were mostly an implementation detail and a workaround for not having stuff the new API gives us. We never meant for them to be part of the public API. An exception to remove these are the key endpoints (which are also internal). We will remove them once we remove the deploy endpoint.
Next up are undocumented endpoints and the old deploy endpoints. These include, GET /api/v1/tags/:tagId, GET /api/v1/projects/:plugin/tags/:versionName, GET /api/v1/projects/:pluginId/pages, and POST /api/v1/projects/:pluginId/versions/:name. We will removed these endpoints as soon as possible, but after API V2 is public and stable, and tooling which uses the deploy API has been migrated. My hope here is around one month from a stable V2 API.
The tags API and pages API was never really documented at all, and I doubt anyone is using them. We’re willing to go back on this with the pages API seeing as we’re probably not going to have a replacement until we redo pages (late summer/early autumn I hope) if anyone is using it. If we do go back on removing it, know that there will likely be a harder break with more broken stuff in the old API when the new pages hit.
The last one here to address is the deploy endpoint. It’s probably one of the more controversial endpoints to get rid of so early, but I believe the gains outweigh the benefits of keeping it around. There are multiple reasons to get rid of it as soon as possible. First off, tools which rely on deploying stuff are much less vulnerable to not being able to switch to a new version, unlike other things which use the API, like plugins. Secondly, the new deploy endpoint is much more secure than the old endpoint. Each user has their API key to upload with, compared to having one shared for all the members of the project. Remember that security risk where we had to invalidate all deploy API keys? Because the new API keys are hashed in the DB, something like that would be impossible with the new keys. Third, with PGP signing gone, we don’t have a good way to determine who uploaded a build using the old endpoint anymore, and it was admintely the one thing PGP was good at making more secure. Fourth, it lets us get rid of the remaining unversioned, authenticated endpoints (creating and revoking keys).
That leaves us with the projects API, versions API, and users API. All of these (except listing users) already have a good enough implementation in the new API. That said, we’ll try to keep around endpoints which projects might use for version checking for a while longer. These are GET /api/v1/projects/:pluginId, GET /api/v1/projects/:pluginId/versions, and GET /api/v1/projects/:pluginId/versions/:name. The next batch of endpoints to be removed will be GET /api/v1/users, GET /api/v1/users/:user, and GET /api/v1/projects. These endpoints will be removed once we have that user list endpoint, and no sooner than 3 months from when the API is stable.
That leaves the endpoints that plugins can use for version checking. Our plans here is to support these for 6-12 months hopefully. HOWEVER, they will likely not continue to work as well as they do now (that might apply to more endpoints if we manage to move fast enough, but these are the ones at the biggest risk). For example, the channels of the project might return an empty list, and the channel of a version might return null in the future once channels don’t exist anymore.
That’s our general plans, but if anyone has anything to say to this, or feel we’re going about this in the wrong way, feel free to say so. We’re trying to get a good balance of keeping the old stuff around for a bit longer, so that people can migrate, and throwing out old stuff that hinders our development progress.