You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Fix documentation inaccuracies found during pre-release audit
README:
- Correct endpoint count from 15 to 23
- Update feature description to list all endpoint categories
(notifications, clones, contacts, calendar, loyalty, killmails were missing)
- Correct test coverage claim from '100%' to '>=98%'
- Update endpoint reference link to reflect 23 methods
docs/authentication.md:
- Add 7 missing scopes to the required OAuth scope table:
read_notifications, read_clones, read_implants, read_contacts,
read_calendar_events, read_loyalty, read_killmails
- Note that wallet_journal shares esi-wallet.read_character_wallet.v1
with wallet_balance
- Correct 'exports the full set' to 'exports a recommended baseline set'
(DEFAULT_SCOPES is intentionally a subset, not the complete scope list)
* Document pagination and caching; fix README fatigue category
- endpoints.md: expand Pagination section with table of paginated methods
and page sizes; add Client utilities section documenting clear_etag_cache();
add Request caching section explaining TTL and ETag layers with examples
- quickstart.md: add Automatic pagination and Request caching sections
- error-handling.md: replace duplicated caching content with cross-reference
to endpoints.md#request-caching
- README.md: restore 'fatigue' to authenticated endpoint category list
(addresses Copilot review comment)
Copy file name to clipboardExpand all lines: docs/endpoints.md
+66-2Lines changed: 66 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -124,9 +124,23 @@ All authenticated endpoints require `EveOnlineClient(auth=...)`. See [Authentica
124
124
125
125
### Pagination
126
126
127
-
Some ESI endpoints return data across multiple pages. The client handles this automatically using the `X-Pages` response header: it fetches page 1, reads the total page count, then sequentially fetches any remaining pages and returns a single combined list. No extra code is needed — just call the method as usual.
127
+
Some ESI endpoints return data across multiple pages. The client handles this automatically:
128
128
129
-
Endpoints that use automatic pagination are marked with *all pages fetched automatically* in their return type description.
129
+
1. It fetches page 1 and reads the `X-Pages` response header to determine the total page count.
130
+
2. It sequentially fetches any remaining pages.
131
+
3. All pages are merged into a single list before returning.
132
+
133
+
No extra code is needed — just call the method as usual.
134
+
135
+
Endpoints with automatic pagination:
136
+
137
+
| Method | Max items per page |
138
+
|---|---|
139
+
|`async_get_wallet_journal()`| 50 |
140
+
|`async_get_contacts()`| 500 |
141
+
|`async_get_killmails()`| 50 |
142
+
143
+
Endpoints that use automatic pagination are also marked with *all pages fetched automatically* in their return type description below.
|`killmail_hash`|`str`| Hash required to fetch the full killmail detail |
531
+
532
+
---
533
+
534
+
## Client utilities
535
+
536
+
### `clear_etag_cache()`
537
+
538
+
Discards all cached responses (both TTL and ETag layers) so the next request to each endpoint fetches fresh data from ESI.
539
+
540
+
```python
541
+
client.clear_etag_cache()
542
+
```
543
+
544
+
Useful when you need up-to-date data immediately, regardless of the remaining cache lifetime.
545
+
546
+
---
547
+
548
+
## Request caching
549
+
550
+
The client uses two automatic caching layers to reduce ESI traffic. Caching is active when a GET endpoint returns an `ETag` header — which is true for all endpoints documented here.
551
+
552
+
### Layer 1 — TTL (`Expires` header)
553
+
554
+
When ESI returns an `Expires` header, the client stores the expiry timestamp alongside the cached data. A repeat call before that time returns the cached result immediately **without making any HTTP request**.
555
+
556
+
```python
557
+
# First call — real HTTP request, Expires stored
558
+
status =await client.async_get_server_status()
559
+
560
+
# Second call within TTL window — no HTTP request, cache returned instantly
561
+
status =await client.async_get_server_status()
562
+
```
563
+
564
+
ESI cache durations vary by endpoint. Common values:
565
+
566
+
| Endpoint | Cache duration |
567
+
|---|---|
568
+
|`/status/`| 30 seconds |
569
+
|`/characters/{id}/online/`| 60 seconds |
570
+
|`/characters/{id}/wallet/`| 120 seconds |
571
+
|`/characters/{id}/skills/`| 120 seconds |
572
+
|`/characters/{id}/industry/jobs/`| 300 seconds |
573
+
|`/characters/{id}/orders/`| 1200 seconds |
574
+
|`/universe/names/`| 3600 seconds |
575
+
576
+
### Layer 2 — ETag (`If-None-Match` / 304)
577
+
578
+
Once the TTL has expired (or if no `Expires` header was present), the client sends the stored `ETag` value in an `If-None-Match` request header. If the data has not changed since it was last fetched, ESI responds with `304 Not Modified` and the client returns the previously cached data **without downloading a response body**.
579
+
580
+
Both layers are fully transparent — no configuration is needed. Use `clear_etag_cache()` to bypass them when fresh data is required.
Copy file name to clipboardExpand all lines: docs/error-handling.md
+1-20Lines changed: 1 addition & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -86,23 +86,4 @@ except EveOnlineRateLimitError as err:
86
86
87
87
## ESI caching headers
88
88
89
-
ESI endpoints each have a server-side cache duration. Fetching within the cache window returns the same data. Common cache times:
90
-
91
-
| Endpoint | Cache duration |
92
-
|---|---|
93
-
|`/status/`| 30 seconds |
94
-
|`/characters/{id}/online/`| 60 seconds |
95
-
|`/characters/{id}/wallet/`| 120 seconds |
96
-
|`/characters/{id}/skills/`| 120 seconds |
97
-
|`/characters/{id}/skillqueue/`| 120 seconds |
98
-
|`/characters/{id}/industry/jobs/`| 300 seconds |
99
-
|`/characters/{id}/orders/`| 1200 seconds |
100
-
|`/universe/names/`| 3600 seconds |
101
-
102
-
The client can use two layers of caching to minimise ESI traffic, but only when a cacheable response has been received (a GET response that includes an `ETag` header):
103
-
104
-
1.**TTL caching (`Expires` header)** — When a response is cached, the client stores its `Expires` value alongside the cached data if the header is present. If you call the same endpoint again before that time is reached, the client returns the cached result immediately without making any HTTP request. If no `Expires` value was stored for a cached entry, this layer is skipped and the request falls through to the ETag layer.
105
-
106
-
2.**ETag caching (`If-None-Match` / 304)** — Once the stored `Expires` time has passed, or when no `Expires` value was stored, the client sends the cached `ETag` in an `If-None-Match` header. If the data has not changed, ESI returns `304 Not Modified` and the client returns the previously cached data without downloading a response body.
107
-
108
-
Use `client.clear_etag_cache()` to discard both layers and force fresh responses on the next requests.
89
+
The client automatically caches ESI responses to reduce traffic and ESI error-budget consumption. See [Endpoints — Request caching](endpoints.md#request-caching) for the full reference including cache durations, TTL behaviour, ETag/304 handling, and `clear_etag_cache()`.
The client caches ESI responses automatically using two layers:
108
+
109
+
1.**TTL** — If ESI returns an `Expires` header, repeated calls before that time skip the HTTP request entirely.
110
+
2.**ETag / 304** — Once the TTL expires, the client sends `If-None-Match`. If the data is unchanged, ESI returns `304 Not Modified` and no response body is downloaded.
111
+
112
+
Both layers are transparent and require no configuration. To force fresh data, call `clear_etag_cache()`:
113
+
114
+
```python
115
+
client.clear_etag_cache()
116
+
status =await client.async_get_server_status() # fresh request
117
+
```
118
+
119
+
See [Endpoints](endpoints.md#request-caching) for the full caching reference.
0 commit comments