Archive-data REST interface

In the event-notification flow the PAS fetches the data to archive from a source microservice over REST. The source service implements a small, standardized interface: an endpoint that returns the data to archive for a reference id (and optional version), plus a set of HTTP headers describing the archive type.

Not all data of an application is relevant long-term — the source service only exposes what should be archived.

Endpoint

The PAS calls the uri configured for the message, substituting {id} (and {version} when the endpoint is versioned) from the ArchiveDataReference. The endpoint returns the raw data in the response body and describes it with these headers:

Header	Required	Description	Example
`Content-Type`	yes	Content type of the data (add a charset if not UTF-8). Avro is recommended	`avro/binary`
`Archive-Data-System`	yes	System that defines the schema. Must match the archive type's system	`JME`
`Archive-Data-Schema`	yes	Archive type / schema name. Must match the archive type	`Decree`
`Archive-Data-Schema-Version`	yes	Positive integer schema version. Must match a known archive type version	`1`
`Archive-Metadata-*`	no	Custom metadata stored with the artifact	`Archive-Metadata-issuer`
`Archive-Storage-Bucket`	no	Overrides the target bucket (normally set by the object storage strategy)	`bit-jme-pas-decree-dev`
`Archive-Storage-Prefix`	no	Overrides the key prefix (normally set by the object storage strategy)	`some-prefix/`

The interface supports business-object versioning; sub-resource versions are not supported. The request timeout is configurable via jeap.processarchive.http.timeout (see Configuration).

Serving binary Avro over REST

Avro is the recommended archive format. The jeap-process-archive-web module registers a Spring MVC HTTP message converter that transparently serializes an Avro-generated class to binary Avro when the controller produces avro/binary:

<dependency>
    <groupId>ch.admin.bit.jeap</groupId>
    <artifactId>jeap-process-archive-web</artifactId>
</dependency>

@GetMapping(value = "/decreedocuments/{id}", produces = AvroWebConstants.AVRO_BINARY)
public DecreeDocument getArchivalDecreeDocument(@PathVariable("id") String id, HttpServletResponse response) {
    response.addHeader("archive-data-system", "JME");
    response.addHeader("archive-data-schema", "DecreeDocument");
    response.addHeader("archive-data-schema-version", "1");
    response.addHeader("archive-metadata-issuer", "John Smith");
    // ... map the domain object to the Avro archive type ...
    return DecreeDocument.newBuilder(/* ... */).build();
}

The Java bindings for archive types are generated by the Archive Type Registry and consumed as Maven dependencies:

<dependency>
    <groupId>ch.admin.bit.jme.archivetype.jme</groupId>
    <artifactId>decree-document-v1</artifactId>
    <version>1</version>
</dependency>

For a versioned artifact, add a {version} parameter to the endpoint and read the version in the controller — see the DiagramController in the jme-process-archive-example project.

Endpoint​

Serving binary Avro over REST​

Related​

Endpoint

Serving binary Avro over REST

Related