Page MenuHomeSoftware Heritage
Create Task
Maniphest T2158

Properly deal with removed endpoints
Closed, MigratedEdits Locked
Actions

Description

D1969 removed several endpoints using origin ids, and D2167 removed some more endpoints related to origin types.

This caused an issue for some users, because one of them started returning 404 because the endpoint doesn't exist (while it used to mean the origin doesn't exist).

We should do something about it.

Possibilities:

  1. Increment the API version number (probably 1.1, as they are relatively minor changes), and make all /api/1/ URLs return an error that is not a 404 (eg. 410 Gone)
  2. Keep the current API version number but return an error (that is not a 404) for the endpoints we removed

Related Objects

Event Timeline

vlorentz triaged this task as Normal priority.Dec 17 2019, 5:02 PM
vlorentz raised the priority of this task from Normal to High.
vlorentz created this task.
vlorentz added a project: Web app.
vlorentz added subscribers: anlambert, zack.
olasd added a subscriber: olasd.Dec 19 2019, 3:45 PM

(I'm dubious about the high priority of this task; Guix has changed their code for the new API)

Regardless of how specific cases have been handled in the past, I agree with your point 2 that removed endpoints should be distinguishable from valid return codes.

Your point 1, a blanket move to a new API version number (even a so-called minor version) without any transition sounds like the worst user experience ever, so let's not do that.

You haven't mentioned other possibilities:

  1. formalize doing usage analysis before removing any endpoint
  2. have a census of our API users and notify them if their use case is being changed
  3. have a generic API user diffusion list and notify that when APIs get modified/deprecated

These will probably be easier to do when we'll have some form of authenticated requests.

As for the specific cases mentioned:

I think D1969 was handled somewhat ok: a multi-month deprecation period, followed by an usage analysis (which turned up minimal usage), followed by removal.

For D2167, I agree that we didn't do a usage analysis beforehand, and that was a mistake. We can still consider adding a redirect from /api/1/origin/<type>/url/<url>/... to /api/1/origin/<url>/... (basically ignoring the type argument), which would bring compatibility with the older API back.

douardda lowered the priority of this task from High to Low.Jan 23 2020, 11:16 AM
douardda added a subscriber: douardda.

Agreed, this no longer need to be a high priority task.

gitlab-migration closed this task as Migrated.Jan 8 2023, 5:01 PM
gitlab-migration claimed this task.
gitlab-migration added a subscriber: gitlab-migration.

This task has been migrated to GitLab.

About · Developer information · Legal