service-api-expanders

The jaxrs-service-api-expanders bundle is a set of expanders capable of generating a Jersey-based JAX-RS implementation of a REST API. Documentation is provided in the form of Swagger (OpenAPI) files that are automatically generated.

• Getting started guide
• Release notes
• Git repository on GitHub

Overview

The expanders generate a REST API implementation based on industry standard practices. Though the HTTP protocol that carries REST is standardized and uniquely defined as described in RFC 7231 and amended with the PATCH method described in RFC 5789, the REST payloads themselves are not. As such, a set of commonly used specifications and practices were adopted to provide a clean implementation.

The following specifications are used to generate a consistent and clean API which is self-documenting:

• The HAL (Hypertext Application Language) specification to return lists of resources, accompanied by navigation data and search metrics.
• The Problem Details specification to describe errors in a meaningful and consistent way.
• The OpenAPI (or Swagger) v3.0 specification for documenting RESTful APIs.

In additions to these specifications, the expanders generate Swagger UI integration to provide a clean and visual interface to the API for developers and users of the application.

Expansion resources

The following expansion resources are available for use in applications:

• org.normalizedsystems.beam:service-api-beam@1.1.0: A beam that contains all resources for the jaxrs-service-api-expanders, which can be combined with other beams.
• net.democritus.api.rest:jaxrs-service-api-expanders@5.2.1: The main expander bundle, which expands the JAX-RS REST stack into the main NS application stack.
• net.democritus.api.rest:jaxrs-service-api-account-security-expanders@5.2.1: An addon expander bundle for the rest-expanders bundle, which adds support for the access control features in the account component of the base-components.
• net.democritus.api.rest:jaxrs-service-api-assets-expanders@5.2.1: An addon expander bundle for the rest-expanders bundle, which supplies an implementation for file resources and upload/download endpoints with the assets component of the base-components.

Development preview

A development preview bundle is available for the jaxrs-service-api-expanders. This is a mirror of the service-api-beam, but containing the latest versions of all resources.

This resource is not intended for use in application development, but rather to preview upcoming changes and test against them in advance. Note that this preview bundle is subject to changes and does not necessarily reflect the future state of the service-api-beam.