Class ApiHttpPolicy

java.lang.Object
com.kingsrook.qqq.api.model.metadata.ApiHttpPolicy
public class ApiHttpPolicy extends Object
HTTP behaviour of an API instance served to the public internet, typically behind a CDN: shared-cache headers and validators for anonymous reads, and an explicit CORS policy.

A public read is a GET or HEAD request that carries no credentials (no Authorization or x-api-key header, no session cookie) and answers 200. Public reads get Cache-Control: public, max-age=N, s-maxage=N, stale-while-revalidate=S, stale-if-error=E, a matching CDN-Cache-Control (RFC 9213), a weak ETag over the body, and 304 Not Modified for a matching If-None-Match. A public read whose handler already set a Cache-Control keeps it (a plain public, max-age=N is expanded the same way). Every other response (credentials, writes, errors) is private, no-store, so a shared cache never stores an answer that depends on who asked.

CORS: public reads answer Access-Control-Allow-Origin: * with no credentials and no Vary: Origin, so one cached copy serves every caller. Other requests are allowed only from getCorsAllowedOrigins() (echoed, with Vary: Origin); preflight OPTIONS requests answer 204.

An ApiInstanceMetaData without a policy keeps the historical behaviour (no cache headers; CORS reflects any origin).

  • Field Details

    • CORS_ALLOWED_HEADERS

      public static final List<String> CORS_ALLOWED_HEADERS

    • CORS_EXPOSED_HEADERS

      public static final List<String> CORS_EXPOSED_HEADERS

    • CORS_MAX_AGE_SECONDS

      public static final int CORS_MAX_AGE_SECONDS
      See Also:

  • Constructor Details

    • ApiHttpPolicy

      public ApiHttpPolicy()

  • Method Details

    • publicCacheControl

      public String publicCacheControl(int maxAgeSeconds)
      The Cache-Control value for a public read with the given max age.

    • cdnCacheControl

      public String cdnCacheControl(int maxAgeSeconds)
      The CDN-Cache-Control value (RFC 9213) for a public read.

    • isCorsAllowedOrigin

      public boolean isCorsAllowedOrigin(String origin)
      Whether an origin may make credentialed / non-public requests.

    • getPublicReadMaxAgeSeconds

      public Integer getPublicReadMaxAgeSeconds()
      Getter for publicReadMaxAgeSeconds (null = public reads get no cache headers).

    • setPublicReadMaxAgeSeconds

      public void setPublicReadMaxAgeSeconds(Integer publicReadMaxAgeSeconds)
      Setter for publicReadMaxAgeSeconds

    • withPublicReadMaxAgeSeconds

      public ApiHttpPolicy withPublicReadMaxAgeSeconds(Integer publicReadMaxAgeSeconds)
      Fluent setter for publicReadMaxAgeSeconds

    • getStaleWhileRevalidateSeconds

      public Integer getStaleWhileRevalidateSeconds()
      Getter for staleWhileRevalidateSeconds

    • setStaleWhileRevalidateSeconds

      public void setStaleWhileRevalidateSeconds(Integer staleWhileRevalidateSeconds)
      Setter for staleWhileRevalidateSeconds

    • withStaleWhileRevalidateSeconds

      public ApiHttpPolicy withStaleWhileRevalidateSeconds(Integer staleWhileRevalidateSeconds)
      Fluent setter for staleWhileRevalidateSeconds

    • getStaleIfErrorSeconds

      public Integer getStaleIfErrorSeconds()
      Getter for staleIfErrorSeconds

    • setStaleIfErrorSeconds

      public void setStaleIfErrorSeconds(Integer staleIfErrorSeconds)
      Setter for staleIfErrorSeconds

    • withStaleIfErrorSeconds

      public ApiHttpPolicy withStaleIfErrorSeconds(Integer staleIfErrorSeconds)
      Fluent setter for staleIfErrorSeconds

    • getEtags

      public boolean getEtags()
      Getter for etags

    • setEtags

      public void setEtags(boolean etags)
      Setter for etags

    • withEtags

      public ApiHttpPolicy withEtags(boolean etags)
      Fluent setter for etags

    • getMaxEtagBodyBytes

      public int getMaxEtagBodyBytes()
      Getter for maxEtagBodyBytes

    • setMaxEtagBodyBytes

      public void setMaxEtagBodyBytes(int maxEtagBodyBytes)
      Setter for maxEtagBodyBytes

    • withMaxEtagBodyBytes

      public ApiHttpPolicy withMaxEtagBodyBytes(int maxEtagBodyBytes)
      Fluent setter for maxEtagBodyBytes

    • getCorsAllowedOrigins

      public List<String> getCorsAllowedOrigins()
      Getter for corsAllowedOrigins

    • setCorsAllowedOrigins

      public void setCorsAllowedOrigins(List<String> corsAllowedOrigins)
      Setter for corsAllowedOrigins

    • withCorsAllowedOrigins

      public ApiHttpPolicy withCorsAllowedOrigins(List<String> corsAllowedOrigins)
      Fluent setter for corsAllowedOrigins