The Oracle Commerce Platform REST framework supports the JAX-RS standard with Jersey as the underlying implementation.
The Jersey configuration defines the components of the JAX-RS application, such as resource classes and components, filters, and additional metadata.
The following diagram shows the flow of the main REST framework components that are used when an HTTP request is made. The REST framework is initiated when a request is received by the Jersey servlet. The servlet is responsible for invoking the provider components in the correct order:
The framework supports multiple versions and/or contexts of the REST JAX-RS API. Each version and context must configure the Jersey servlet with the appropriate context root URI.
The Jersey servlet is configured in the web.xml
file to reference the JAXRSApplication
class which, during server startup, gets the set of providers and resources from the RestResourceRegistry
Nucleus component for that version. The web.xml
file also includes the appropriate validation registry. These registries provide the configuration for a specific context or version, for example, /public/v1
. Each context and version of the API is configured with its own Web application and Jersey servlet, for example, /public/v1
would be a separate Web application and servlet from /public/v2
or/admin/v1
.
The following is an example of a web.xml
configuration:
<servlet> <servlet-name>Jersey</servlet-name> <servlet-class>atg.service.jaxrs.JerseyServletWrapper</servlet-class> <init-param> <param-name>atg.service.jaxrs.JerseyServletWrapper.servletClasses </param-name> <param-value>org.glassfish.jersey.servlet.ServletContainer, atg.service.swagger.SwaggerBootstrap</param-value> </init-param> <!-- Params for JerseyServletWrapper servlet --> <init-param> <param-name>javax.ws.rs.Application</param-name> <param-value>atg.service.jaxrs.JAXRSApplication</param-value> </init-param> <init-param> <param-name>jersey.config.server.provider.classnames</param-name> <param-value>atg.service.swagger.SwaggerApiListingResource, io.swagger.jaxrs.listing.SwaggerSerializers</param-value> </init-param> <init-param> <!-- Params for JAXRSApplication --> <param-name>atg.service.jaxrs.JAXRSApplication.resourceRegistryPath </param-name> <param-value>/atg/dynamo/service/jaxrs/RestResourceRegistry</param-value> </init-param> <init-param> <param-name>atg.service.jaxrs.JAXRSApplication.validatorRegistryPath </param-name> <param-value>/atg/dynamo/service/validator/ValidatorRegistry</param-value> </init-param> <init-param> <!-- Params for SwaggerBootstrap servlet --> <param-name>atg.service.swagger.SwaggerBootstrap.bootstrapService </param-name> <param-value>/atg/dynamo/service/swagger/SwaggerBootstrapService </param-value> </init-param> <load-on-startup>2</load-on-startup> <async-supported>true</async-supported> </servlet> <servlet-mapping> <servlet-name>Jersey</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping>
When setting up the web.xml
file there are four configurations that you must provide.
You must configure a
JAXRSApplication
class that will be used as the Jersey access point for the provider and resource classes in the API.The
RestResourceRegistry
Nucleus component should be configured with the provider and resources for the API that are available to theJAXRSApplication
instance. For additional information on theRestResourceRegistry
, refer to the Working with REST Resource Nucleus Components section.The
ValidatorRegistry
component must be configured with the validator XML schema definition file that validates request input and filters the response output. For information on configuring validation, refer to the Validating Input and Filtering Output section.You should also configure the
SwaggerBootstrapService
component, which scans the API and builds the Swagger definitions and documentation. For information on configuring Swagger definitions, refer to the Self Documenting with Swagger section.