Package com.tccc.kos.commons.core.dispatcher.annotations

Annotation Interface ApiEndpoint

@Target(METHOD) @Retention(RUNTIME) @Documented public @interface ApiEndpoint
The ApiEndpoint annotation is used to declare and document an HTTP (RESTful) endpoint. It is also used by the kOS "OpenAPI Engine" to dynamically generate documentation for the currently installed set of endpoints.

The return value from the annotated method will be converted to json and sent to the client. This can be modified in the following ways:

  • @JsonView(viewClass) : This annotation can be used to restrict which fields from the response are sent back to the client. This view is provided to the json mapper when converting the response.
  • stream=true parameter : This parameter indicates that the handler will write directly to the response output stream so the return value should be ignored. This can be used to serve arbitrary content or return a different style response to a client that expects a particular response format that doesn't match the standard kOS envelope format.
A base url can optionally be specified in the @ApiController annotation. This will be prefixed to every endpoint defined within the controller. For example, to prefix all mappings with "/myService", use @ApiController(base = "/myService") on the class.

It is possible to add request handlers from classes that do not use the @ApiController but the standard kOS infrastructure typically looks for instances in a BeanContext with this annotation and automatically processes the associated endpoints.

When a method is annotated with a mapping annotation additional annotations may be used on the method parameters to automatically gain access to data from the request. For more details please see the following annotations:

  • @HandleVariable
  • @PathVariable
  • @RequestBody
  • @RequestParam
  • @Tracker
Endpoints support versioning via the version parameter. By default, the version will come from the version indicated in @ApiController but setting the version param in the @ApiEndpoint annotation will override it. The version will be returned as part of the standard kOS response envelope.
Since:
1.0
Version:
2023-02-16

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    ApiEndpoint.Param
     

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    desc
    Description of the endpoint.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    DELETE
    Sets the URL path of the associated DELETE operation.
    boolean
    deprecated
    If true, endpoint is deprecated
    String
    GET
    Sets the URL path of the associated GET operation.
    boolean
    hidden
    If true, exclude endpoint from openapi docs.
    boolean
    internal
    If true, endpoint is internal and should not be used for production systems as the endpoint may change at any time
    ApiEndpoint.Param[]
    params
    Documents the URL parameters.
    String
    POST
    Sets the URL path of the associated POST operation.
    String
    PUT
    Sets the URL path of the associated PUT operation.
    boolean
    stream
    If true, this returns a stream, not json data.
    String[]
    tags
    Tags that can be used in auth handlers.
    String
    version
    The api version.

  • Element Details

    • desc

      String desc
      Description of the endpoint.

    • GET

      String GET
      Sets the URL path of the associated GET operation.
      Default:
      ""

    • PUT

      String PUT
      Sets the URL path of the associated PUT operation.
      Default:
      ""

    • POST

      String POST
      Sets the URL path of the associated POST operation.
      Default:
      ""

    • DELETE

      String DELETE
      Sets the URL path of the associated DELETE operation.
      Default:
      ""

    • params

      ApiEndpoint.Param[] params
      Documents the URL parameters. Name of @Param should match a named parameter in the request handler.
      Default:
      {}

    • tags

      String[] tags
      Tags that can be used in auth handlers.
      Default:
      {}

    • version

      String version
      The api version.
      Default:
      ""

    • stream

      boolean stream
      If true, this returns a stream, not json data.
      Default:
      false

    • deprecated

      boolean deprecated
      If true, endpoint is deprecated
      Default:
      false

    • internal

      boolean internal
      If true, endpoint is internal and should not be used for production systems as the endpoint may change at any time
      Default:
      false

    • hidden

      boolean hidden
      If true, exclude endpoint from openapi docs.
      Default:
      false