jsonapi4j
/jsonapi4j
Pomaga budować backendy JSON:API we frameworku jsonapi4j: zasoby, relacje, operacje, dokumenty złożone, walidację, bezpieczeństwo i testy RestAssured.
- Autor
- moonworm ↗
- Repozytorium
- jsonapi4j ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 17.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 11
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 2
Brak sygnałów. Repozytorium zmienione 17.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Pomaga budować backendy JSON:API we frameworku jsonapi4j: zasoby, relacje, operacje, dokumenty złożone, walidację, bezpieczeństwo i testy RestAssured.
Oryginalny opis (EN)
How to build and reason about JSON:API backends with the jsonapi4j framework (pro.api4) — resources, relationships (to-one/to-many), operations, compound documents/includes, validation, security, config, and RestAssured testing. Use whenever working in a codebase that depends on jsonapi4j (imports under pro.api4.jsonapi4j, @JsonApiResource / @JsonApiRelationship / @JsonApiResourceOperation annotations, a /jsonapi rootPath), or when the user mentions jsonapi4j, JSON:API resources/relationships/compound-docs in such a project.
Jak działa
- Mental model: the three-part anatomy
- Quick checklist for a new resource
- Reference index — open on demand
Podgląd SKILL.md
---
name: jsonapi4j
description: How to build and reason about JSON:API backends with the jsonapi4j framework (pro.api4) — resources, relationships (to-one/to-many), operations, compound documents/includes, validation, security, config, and RestAssured testing. Use whenever working in a codebase that depends on jsonapi4j (imports under pro.api4.jsonapi4j, @JsonApiResource / @JsonApiRelationship / @JsonApiResourceOperation annotations, a /jsonapi rootPath), or when the user mentions jsonapi4j, JSON:API resources/relationships/compound-docs in such a project.
---
# Working with jsonapi4j
jsonapi4j (`pro.api4`, by Aliaksei Taliuk) is a persistence-agnostic Java framework for building
[JSON:API](https://jsonapi.org/)-compliant REST APIs. No JPA/ORM required — it works over any data
source (JdbcTemplate, a REST client, in-memory, …). It ships **three** integrations: **Spring Boot**,
**Quarkus**, and plain **Jakarta Servlet**. Docs: https://api4.pro/.
This skill is the consumer's guide — how to *build with* the framework. Keep `SKILL.md` lean; open the
matching `reference/<file>.md` when you go deep on a topic (paths below). When you confirm a new pattern
or quirk, add it to the relevant reference file.
**When you write anything down** — a note in `reference/`, the app's README, or an operation
`description` that ships in the published OpenAPI document — document what the *caller* must choose,
know, or watch out for, never what the code does. "Returns a paginated list of users; `page[cursor]`
comes from the previous response's `links.next`" earns its place; "iterates the result set and maps
each row" does not. A rule that fits in a sentence gets a sentence, not a code block.
**Versioned behavior:** edge behaviors are version-specific (current line is 1.11.x). Treat the
"known behaviors" notes as "verify against the version on your classpath and the framework's own
tests," not gospel. The canonical, runnable reference is the framework's `examples/` sample apps
(Spring Boot / Quarkus / Servlet over a shared domain).
## Mental model: the three-part anatomy
Every resource (and every relationship) is split into small single-purpose classes, auto-discovered as
beans (Spring `@Component` / Quarkus CDI / registered in the Servlet context):
1. **`Resource<DTO>`** — maps a backend DTO to a JSON:API resource: `resolveResourceId` +
`resolveAttributes`. Annotated `@JsonApiResource(resourceType = "users")`.
2. **`Relationship<REF>`** — maps to a *resource identifier* (`{type, id}` + optional identifier meta/links).
It has **no attributes**. Annotated
`@JsonApiRelationship(relationshipName = "citizenships", parentResource = UserResource.class)`.
Use `ToOneRelationship<REF>` / `ToManyRelationship<REF>`.
3. **`*Operations`** — the data access. Annotated `@JsonApiResourceOperation(resource = ...)` or
`@JsonApiRelationshipOperation(relationship = ...)`. Implement the composite
`ResourceOperations<DTO>` / `ToOneRelationshipOperations<PARENT, CHILD>` /
`ToManyRelationshipOperations<PARENT, CHILD>` — each method defaults to throwing
`OperationNotFoundException`, so you override only what your resource actually supports, plus the
matching `validateXxx` hooks.
4. **The DTO is deliberately *wider* than the attributes** — it also carries the foreign keys that
relationships need (so relationships can resolve linkage off the parent without extra queries).
```java
@Component
@JsonApiResource(resourceType = "users")
public class UserResource implements Resource<UserDbEntity> {
public String resolveResourceId(UserDbEntity u) { return u.getId(); }
public UserAttributes resolveAttributes(UserDbEntity u) {
return new UserAttributes(u.getFullName(), u.getEmail());
}
}
```
(See the real thing: `examples/jsonapi4j-sampleapp-domain/.../domain/user/UserResource.java`.)
## Quick checklist for a new resource
1. **DTO** (carry FKs for relationships) + `Resource<DTO>` + an `*Attributes` class holding **only this
resource's own data**.
2. **`ResourceOperations<DTO>`**: `readById`, `readPage` (+ `validateReadById` / `validateReadMultiple`);
throw `ResourceNotFoundException` on a miss. Choose a pagination strategy for `readPage`.
3. **Relationships**: `ToOne/ToManyRelationship<Ref>` — **prefer lightweight refs** over heavy DTOs (any
type works; only `id`/`type`/meta are read, so it's your call);
`*Operations` with `readOne`/`readMany` (+ `readOneForResource`/`readManyForResource` and/or batch
ops to avoid N+1 on includes).
4. **Security**: add your web framework's URL-prefix rule if the resource is public; layer the AC plugin
for field-level/ownership gating.
5. **Compound docs**: if the type is includable, support `filter[id]` on its `readPage` (+ a
`jsonapi4j.cd.mapping.<type>.maxBatchSize`). A `cd.mapping.<type>.url` is only for types another
service serves — same-app types are read in-process.
6. **OpenAPI** (if the OAS plugin is on): `@OasResourceInfo(attributes = XAttributes.class)` on the
`Resource` — without it the published schema is empty. Declare `sortableFields` / `filters` on the
operation, or they go undocumented even though they work.
7. **Tests**: RestAssured by-id/filter/404/400 + `?include=` cases (random port is fine; CD profile).
## Reference index — open on demand
- **`reference/resources-and-operations.md`** — Resource contract, the composite operations, pagination
modes and `PaginationAwareResponse` factories (incl. `null` vs `empty()`), the one-mapper-per-resource
data-layer rule.
- **`reference/relationships.md`** — to-one/to-many, lightweight refs vs full DTOs,
`readOneForResource`/`readManyForResource` and batch ops (N+1 avoidance), edge data in identifier meta.
- **`reference/compound-documents.md`** — `?include=`, resolution (in-process for same-app types,
`cd.mapping` over HTTP for cross-service), multi-hop, synthetic-primary caveat, header/param propagation.
- **`reference/performance.md`** — `filter[id]` batching, in-house resolution, parallel `ExecutorService`,
hop/size caps, the compound-docs cache + `Cache-Control`.
- **`reference/validation-and-security.md`** — `validateXxx` hooks, the fluent `JsonApiRequestValidator`,
exceptions (400/404/custom), the two independent security layers + the AC plugin.
- **`reference/configuration.md`** — the `jsonapi4j.*` property reference.
- **`reference/openapi.md`** — the generated OpenAPI document: `@OasResourceInfo` / `@OasOperationInfo`,
which query params are published only when declared, OAuth2 scopes per grant flow, `OasCustomizer`
and the springdoc hand-off.
- **`reference/testing.md`** — RestAssured black-box patterns; `?include=` tests; test profiles;
Testcontainers/Flyway/auth stubs.
- **`reference/separation-of-concerns.md`** — attribute ownership; migrating a denormalized field out to
an `?include`d relationship safely.
- **`reference/known-behaviors.md`** — version-specific quirks (related-URL 404s, to-one linkage
rendering, null refs, cursor meta key, enum attributes, etc.).
Pliki w paczce (11)
- SKILL.md 7 KB
- reference/compound-documents.md 3 KB
- reference/configuration.md 5 KB
- reference/known-behaviors.md 2 KB
- reference/openapi.md 8 KB
- reference/performance.md 3 KB
- reference/relationships.md 8 KB
- reference/resources-and-operations.md 5 KB
- reference/separation-of-concerns.md 2 KB
- reference/testing.md 2 KB
- reference/validation-and-security.md 6 KB
Wersje
W bazie nie ma innych skilli o nazwie jsonapi4j.
Migawka bazy z 13.11.2026 · wersja paczki 457cadbe97ac (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100laravel-jsonapi
Buduje w Laravel 13 endpointy zgodne ze specyfikacją JSON:API z użyciem natywnej klasy bazowej JsonApiResource. - 100rest-api-test-generator
Generuje testy REST API w RestAssured lub MockMvc z zapobieganiem pętlom i walidacją krok po kroku. - 100restassured-testing
Pisze testy API w Javie z REST Assured: statusy, ścieżki JSON i XML, autoryzację, schematy i raporty w Maven lub Gradle. - 100quarkus-dev-services-and-testing
Prowadzi testowanie w Quarkus: Dev Services bez konfiguracji, @QuarkusTest, @QuarkusIntegrationTest, zasoby testowe, RestAssured, @InjectMock, profile i ciągłe testowanie. - 95testing-patterns
Podpowiada wzorce testów w Quarkus: @QuarkusTest, RestAssured, Mockito, Dev Services i testy integracyjne. - 100restassured-testing
Wzmacnia i przyspiesza testy API w Javie: zbyt luźne asercje, wolne sekwencyjne wywołania HTTP i ręczne parsowanie JSON w REST Assured.