- Java 100%
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 #
- Run
mvn clean installto build your application - Create or update the database schema with
java -jar target/prefix-1.0-SNAPSHOT.jar db migrate config.yml - Optionally, insert test data with
java -jar target/prefix-1.0-SNAPSHOT.jar db seed config.yml(use--orders Nto change the default of 20 orders) - Convert a database UUID to an API ID with
java -jar target/prefix-1.0-SNAPSHOT.jar id encode ord <uuid>, and back withid decode <api-id>. With no values, both read one value per line from stdin, for examplepsql -tAc "SELECT id FROM orders" | java -jar target/prefix-1.0-SNAPSHOT.jar id encode ord - Optionally, run mutation tests with
mvn test-compile org.pitest:pitest-maven:mutationCoverage. The report is intarget/pit-reports/index.html - Start application with
java -jar target/prefix-1.0-SNAPSHOT.jar server config.yml - 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/*, orapplication/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:
- 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.
VarynamesAcceptas well asContent-Type. Rule 114 names onlyContent-Type, butAcceptis the header that drives the choice. A cache that ignores it serves the wrong version.- 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.
limitis the page size. The default is 20, and the largest value is 100. A value outside that range gives 400.afteris 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:
- The ID alone cannot sort by time, because
UuidV7Generatorhashes the timestamp field. The ID breaks a tie, becausecreated_atis not unique. - 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. - 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.
- 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 onorder_idin 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--portto listen on another port.db <subcommand> <config>runs a Liquibase task. The subcommands aremigrate,status,rollback,tag,test,drop-all,dump,fast-forward,generate-docs,prepare-rollback,calculate-checksum,clear-checksums, andlocks.db seed <config>inserts test orders and payments.id encode <type> [uuid...]andid 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:
- A 401 response carries no
WWW-Authenticateheader. Javalin returns its own problem body for an unauthorized request, and the application does not add the challenge header. - 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.
- The health check moved from port 8081 to port 8080. There is one port now, and
/healthcheckneeds 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.