reform-api-standards's Introduction

Deprecation of APIs or API endpoints

Added an annotation named @APIDeprecated for classes and methods that add warning headers to the responses generated by the API.

A typical usage would be to add the @APIDeprecated annotation to a method as in the following example.

    @RequestMapping("/deprecated")
    @APIDeprecated(name = "Deprecated Endpoint",
            date = "01/06/2018",
            link = "https://example.org/docs/api/deprecated/",
            note = "Just a note, upgrade your client code!!!")
    public String deprecated() {
        return "Greetings from deprecated Class Controller!";
    }

The annotation has the attributes that are used for forming a Warning header.

name for friendly name of the endpoint,
expireDate for the date which the endpoint will cease to serve,
docLink for the details of documentation regarding the API updates
note for optional notes to the clients

A sample of the Warning header is as follows:

warning →The UserProfileEndpoint is deprecated and will be removed by 20/09/2017. Please see https://example.org/docs/api/deprecated/ for details. Just note that

It is possible to add the @APIDeprecated annotation on top of a @Controller class to deprecate all the endpoints served by that @Controller at once.

@RestController
@APIDeprecated(name = "Deprecated API set",
        expireDate = "30/09/2018",
        docLink = "https://example.org/docs/api/deprecated/",
        note = "Just a note, upgrade your client code!!!")
public class DeprecatedClassController {

    @RequestMapping("/depclass")
    public String deprecated() {
        return "Greetings from deprecated Class Controller!";
    }

}

Recommend Projects