Search code examples
resthttpapi-design

How do I indicate a REST API endpoint is removed

I have an endpoint

DELETE /events/<id>

In the new version of the API, we are going to remove this API.

Now if the client requests the same URL what status code should I output?

I found a few options.

  1. 410 Gone. This is the closest one. But it relates to resources. It's not about managing API. What I think it means is, If GET /events/1 works then it doesn't make sense to state /events/1 is Gone
  2. 301 Moved Permanently and 302 Found. They are for redirection. But the replacement is not a GET call
  3. 405 Method Not Allowed. It makes sense as the method DELETE is now allowed anymore. But it doesn't say it used to be allowed in the past(not sure if we need it)

Other http methods supported in this endpoint are,

GET /events/<id>/
POST /events/
POST /events/<id>/actions/

Just to clarify. When I google the topic I get more information about Resources. But here I'm concerned about depreciation and removal of API. It's more of a management.

Solution

  • You got some things twisted here.

    DELETE is the verb and indicates a method, not an endpoint.

    /events this is your endpoint.

    MDN suggests 410 Gone for resources that have been removed. Resource in a generic http context can be anything.

    The HyperText Transfer Protocol (HTTP) 410 Gone client error response code indicates that access to the target resource is no longer available at the origin server and that this condition is likely to be permanent.

    https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410

    If you want to show that a method has been removed but the endpoint is still there, you would probably use 405 Method not allowed.

    You should also consider versioning the API.