API — Overview

BaseUrl

All LoL APIs expose three prefixes (Spring @RequestMapping, src/main/java/com/safjnest/spring/controller/):

{shard} is LeagueShard (no.stelar7.api.r4j.basic.constants.api.regions.LeagueShard) validated by LolApiParameters.requiredShard (src/main/java/com/safjnest/spring/controller/LolApiParameters.java:163) on platform-scoped endpoints. Search is global by default; its optional shard query parameter limits results to one active shard. Active values from LeagueShardUtils.getActives (src/main/java/com/safjnest/lol/utils/LeagueShardUtils.java:64): EUW1, NA1, KR, EUN1, JP1, BR1, LA1, LA2, TR1, RU, OC1, VN2, SG2, TW2, ME1. No authentication — protection only via validation and RiotScheduler.

curl "https://api.safjnest.com/api/lol/search?q=Faker%23EUW"
curl "https://api.safjnest.com/api/lol/search?q=Faker%23EUW&shard=EUW1"
curl "https://api.safjnest.com/api/lol/EUW1/profile/abc-puuid"
curl "https://api.safjnest.com/api/lol/leaderboard?queue=RANKED_SOLO_5X5&page=1&limit=20"
curl "https://api.safjnest.com/api/status"

Envelope — ApiResult and HTTP mapping

Services return ApiResult<T> (src/main/java/com/safjnest/lol/model/ApiResult.java:3):

public record ApiResult<T>(Status status, T payload, ResponseMetadata metadata) {
    public enum Status { READY, PARTIAL, PENDING, NOT_FOUND }
}

LolApiResponses

LolApiResponses.from (src/main/java/com/safjnest/spring/controller/LolApiResponses.java:14) maps ApiResult → HTTP:

return switch (result.status()) {
    case READY, PARTIAL -> ResponseEntity.ok(result.payload());
    case PENDING -> ResponseEntity.status(HttpStatus.ACCEPTED)
        .body(new LolApiError(HttpStatus.ACCEPTED.value(), pendingCode, pendingMessage, result.metadata()));
    case NOT_FOUND -> throw new ResponseStatusException(HttpStatus.NOT_FOUND, notFoundMessage);
};

POST /profile/{puuid}/refresh is the only one returning 204 No Content on success (LolController.java:88).

LolApiError — 202 and 4xx errors

LolApiError (src/main/java/com/safjnest/spring/dto/LolApiError.java:5) — sole Spring DTO for errors (ADR-0005/0007):

public record LolApiError(int status, String code, String message, ResponseMetadata metadata) {}

Example 202:

{
  "status": 202,
  "code": "profile_pending",
  "message": "Profile initialization is pending",
  "metadata": { "lastUpdate": null, "refresh": true, "filter": { "...": "..." } }
}

GET /profile/{puuid} adds header X-Profile-Refresh: true when metadata.refresh is true (LolController.java:294).

Pending code catalog (see reference/errors.mdx):

profile_pending, match_pending, leaderboard_pending, champion_pending, champion_tier_list_pending, champion_data_pending, profile_activity_pending, profile_matchups_pending, profile_records_pending.

ResponseMetadata — pagination / lastUpdate / refresh / filter

ResponseMetadata (src/main/java/com/safjnest/lol/model/ResponseMetadata.java:3):

public record ResponseMetadata(Pagination pagination, Long lastUpdate, Boolean refresh, Filter filter) {
    public record Pagination(Integer page, Integer pageSize, Integer limit, Integer offset, Long total, Long pages, Boolean hasMore) {}
}

• pagination — page/pageSize for leaderboard (LeaderboardController.java:46), limit/offset/total/hasMore for matches (LolController.java:123), pages for leaderboard.
• lastUpdate — epoch millis of last update (null if pending).
• refresh — true → client should re-check; also used as header X-Profile-Refresh.
• filter — Filter that generated the data (echo for debugging).

LolApiParameters — centralized validation

Every parameter goes through LolApiParameters (src/main/java/com/safjnest/spring/controller/LolApiParameters.java:27). Errors → ResponseStatusException(400) via invalid (:235), mapped by LolApiExceptionHandler.

LolApiResponses — complete mapping

Shown above. LolApiExceptionHandler (src/main/java/com/safjnest/spring/controller/LolApiExceptionHandler.java:23) translates:

CORS *

LolApiConfig.addCorsMappings (src/main/java/com/safjnest/spring/config/LolApiConfig.java:42):

registry.addMapping("/api/lol/**").allowedOrigins("*").allowedMethods("GET","POST","OPTIONS").allowedHeaders("*");
registry.addMapping("/api/status").allowedOrigins("*").allowedMethods("GET","OPTIONS").allowedHeaders("*");

All browser clients can call without custom preflight.

Jackson MixIn

LolApiConfig.configureMessageConverters (src/main/java/com/safjnest/spring/config/LolApiConfig.java:27):

ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(new JavaTimeModule());
mapper.addMixIn(ChampionStatistics.class, FilterApiMixin.class);
mapper.addMixIn(Build.class, FilterApiMixin.class);
mapper.addMixIn(Filter.class, FilterApiVisibilityMixin.class);
converters.add(new MappingJackson2HttpMessageConverter(mapper));

• FilterApiMixin (:36): @JsonIgnoreProperties("filter") on ChampionStatistics and Build — the internal filter field is not serialized in response JSON.
• FilterApiVisibilityMixin (:39): @JsonAutoDetect(fieldVisibility = ANY) on Filter — ensures field serialization even when Filter is included in ResponseMetadata.

Shared codec for Mongo/Redis: JsonCodec (src/main/java/com/safjnest/utils/JsonCodec.java:17) with FIELD ANY, GETTER NONE, JavaTimeModule, WRITE_DATES_AS_TIMESTAMPS=false.

Pattern index — all routes

/api/lol/{shard} — LolController (LolController.java:36)

/api/lol — global

/api — system

Note: the spec says "17 patterns" — the table actually lists 23. The 17 canonical documents are 1–12 + 13–17; the remaining (records, profile/indexables, ai/training, status, livegame-by-name, profile/records) bring the total to 23.

Quick examples

# Search across every shard, or limit it with `shard`
curl "https://api.safjnest.com/api/lol/search?q=Hide%20on%20bush%23KR1"
curl "https://api.safjnest.com/api/lol/search?q=Hide%20on%20bush%23KR1&shard=EUW1"

# Profile (handle 202)
curl -i "https://api.safjnest.com/api/lol/EUW1/profile/abc-123-puuid"

# Leaderboard
curl "https://api.safjnest.com/api/lol/leaderboard?queue=RANKED_SOLO_5X5&rank=MASTER&page=1&limit=20"

# Champion tier list
curl "https://api.safjnest.com/api/lol/champions/tier-list?patch=15.6&rank=EMERALD&region=EUW1"

# Records
curl "https://api.safjnest.com/api/lol/records/KILLS?region=EUW1&limit=20&offset=0"

# Status
curl "https://api.safjnest.com/api/status"