Skip to content

Latest commit

 

History

History
51 lines (36 loc) · 3.03 KB

deprecating_api_endpoints.md

File metadata and controls

51 lines (36 loc) · 3.03 KB

Deprecating API endpoints

As for deprecation indication using HTTP status code there is no clear specification.

Various answers on StackOverflow and the like tend towards: 410 Gone alternatively: 405 Method Not Allowed

Some suggest using: 301 Moved Permanently or 302 Found.

Some point to: 501 Not Implemented

But based on this:

501 is the appropriate response when the server does not recognize the request method and is incapable of supporting it for any resource

Quoted from: MDN, it believe this works on a more fundamental level.

I believe the HTTP status code: 410 Gone could be used but is not the prettiest solution BUT it could be combined with redirects. Alternatively: 405 Method Not Allowed might be a better and with better control with assistance: Allow header to solve this:

  • You have an API and a resource which can be fetched via: GET, it would normally return the resource and the HTTP status code: 200 Ok
  • If the API is deprecated one could return 308 Permanent Redirect for a period of time indicating the replacement via the Location header, like a newer version: /api/v1 to /api/v2 and this would work for both: POST and GET where 301 Moved Permanently only works for GET
    • If no replacement is in available return: 410 Gone could be used
  • In due time and after adoption have been made for the new API endpoint, use: 410 Gone since the API endpoint is gone and it will not come back, personally I think: 410 Gone is the best fit.
sequenceDiagram
    autonumber
    
    Consumer->>API: METHOD /api/v{version}/{namespace}/{entity}/*
    activate API
    alt Alternative for deprecated API endpoint exist
        API->>Consumer: Return HTTP status code: 308 Permanent Redirect + Location header
    else Alternative for deprecated API endpoint do not exist
        API->>Consumer: Return HTTP status code: 410 Gone
    end
    deactivate API
Loading

For the Swagger part, do see my TIL on that:

Resources and References