Dropwizard playground
Files
README.md

prefix-api #

A Javalin application. It was a Dropwizard application until 2026-10-06; see "Notes on the move from Dropwizard" at the end.

How to start the prefix-api application #

  1. Run mvn clean install to build your application
  2. Create or update the database schema with java -jar target/prefix-1.0-SNAPSHOT.jar db migrate config.yml
  3. Optionally, insert test data with java -jar target/prefix-1.0-SNAPSHOT.jar db seed config.yml (use --orders N to change the default of 20 orders)
  4. Convert a database UUID to an API ID with java -jar target/prefix-1.0-SNAPSHOT.jar id encode ord <uuid>, and back with id decode <api-id>. With no values, both read one value per line from stdin, for example psql -tAc "SELECT id FROM orders" | java -jar target/prefix-1.0-SNAPSHOT.jar id encode ord
  5. Optionally, run mutation tests with mvn test-compile org.pitest:pitest-maven:mutationCoverage. The report is in target/pit-reports/index.html
  6. Start application with java -jar target/prefix-1.0-SNAPSHOT.jar server config.yml
  7. To check that your application is running enter url http://localhost:8080

Endpoints #

Method and path Scope Media type
GET /healthcheck none application/json
GET /orders orders:read application/x.marko.order+json;version=1
GET /orders/{id} none application/x.marko.order+json;version=1
GET /orders/{id}/payments payments:read application/x.marko.payment+json;version=1
GET /payments/{id} payments:read application/x.marko.payment+json;version=1

GET /orders returns one page of orders, newest first. GET /orders/{id}/payments returns one page of the payments of one order, oldest first. Both pages carry a cursor; see Pagination below.

orders:read is new. Add it to the API in Auth0, and grant it to the clients that need the list.

Media type versioning #

Every resource answers with a versioned custom media type, in the form that rule 114 of the Zalando REST API guidelines prescribes:

application/x.<custom-media-type>+json;version=<version>

The custom type names are x.marko.order and x.marko.payment. Both are at version 1. One type covers both shapes of a resource, because the page wrapper carries no schema of its own.

Content-Type: application/x.marko.order+json;version=1
Vary: Accept, Content-Type

A client asks for a version with the Accept header:

curl -H 'Accept: application/x.marko.order+json;version=1' http://localhost:8080/orders/ord_...

The server accepts these Accept values, and answers 406 for anything else:

  • no header at all, */*, application/*, or application/json
  • the custom type of that resource, with no version parameter
  • the custom type of that resource, with version= the version the server writes

Three notes:

  1. Raise the version only for an incompatible change of the payload schema. A new optional field is compatible, so it needs no new version. The rule applies to the payload only, never to the URI or the method.
  2. Vary names Accept as well as Content-Type. Rule 114 names only Content-Type, but Accept is the header that drives the choice. A cache that ignores it serves the wrong version.
  3. The health check is not a resource representation, so it keeps plain application/json.

ApiMediaType holds the type names and the versions. Add an entry there for a new resource.

Pagination #

GET /orders and GET /orders/{id}/payments both use a keyset cursor. Each one takes the same two query parameters.

  • limit is the page size. The default is 20, and the largest value is 100. A value outside that range gives 400.
  • after is the ID of the last item of the page before. Leave it out for the first page.

The response holds the page and the cursor of the next page:

{
  "data": [ { "id": "ord_6knYRKbSBTCu9mmjYMsdyE", "currency": "SEK", "totalAmount": 27150,
              "status": "paid", "createdAt": "2026-09-28T18:24:00Z" } ],
  "nextCursor": "ord_7PSs54XvKk3KLpckmBOPgc"
}

nextCursor is null on the last page. Send it back as after to read the page that follows.

The two lists differ in the sort direction only:

List Sort Index
GET /orders created_at DESC, id DESC orders_created_at_id_idx
GET /orders/{id}/payments created_at, id payments_order_id_created_at_id_idx

Orders read newest first, because a client wants the newest order. The payments of one order read oldest first, because a payment history reads forward in time.

GET /orders/{id}/payments returned a bare JSON array before. It now returns the same page object as GET /orders. The payments themselves did not change, so x.marko.payment stays at version 1.

payments_order_id_created_at_id_idx starts with order_id, so the older payments_order_id_idx is now redundant. Drop it in a later change set to save the write cost.

Four notes on the design:

  1. The ID alone cannot sort by time, because UuidV7Generator hashes the timestamp field. The ID breaks a tie, because created_at is not unique.
  2. The server reads the item that the cursor names, to get its created_at. An unknown cursor gives 404, and a malformed one gives 400.
  3. A payment cursor must belong to the order in the path. A cursor from another order gives 404, because that payment is never part of this list.
  4. The row comparison (created_at, id) < (?, ?) becomes an index condition, so the database reads a page without a sort. The payments query adds the equality on order_id in front of it.

Health Check #

To see your applications health enter url http://localhost:8080/healthcheck

Commands #

Run java -jar target/prefix-1.0-SNAPSHOT.jar --help for the command list, and ... <command> --help for the options of one command.

  • server <config> starts the HTTP server. Use --port to listen on another port.
  • db <subcommand> <config> runs a Liquibase task. The subcommands are migrate, status, rollback, tag, test, drop-all, dump, fast-forward, generate-docs, prepare-rollback, calculate-checksum, clear-checksums, and locks.
  • db seed <config> inserts test orders and payments.
  • id encode <type> [uuid...] and id decode [api-id...] convert between database UUIDs and API IDs.

Logging #

Logback reads src/main/resources/logback.xml. The logging block of config.yml stays in the file, but the application ignores it.

Notes on the move from Dropwizard #

Three behaviours changed on purpose:

  1. A 401 response carries no WWW-Authenticate header. Javalin returns its own problem body for an unauthorized request, and the application does not add the challenge header.
  2. A malformed ID in a path gives 400, not 404. Javalin validates the path parameter, and a value of a wrong form fails that check.
  3. The health check moved from port 8081 to port 8080. There is one port now, and /healthcheck needs no token.

The token check runs before the path parameter check. A request with a malformed ID and no token gives 401, as it did before.