Skip to content

Enhance KiCad API with stock quantity, datasheet URL, and HTTP caching#1232

Open
Sebbeben wants to merge 5 commits intoPart-DB:masterfrom
Sebbeben:feature/kicad-api-improvements
Open

Enhance KiCad API with stock quantity, datasheet URL, and HTTP caching#1232
Sebbeben wants to merge 5 commits intoPart-DB:masterfrom
Sebbeben:feature/kicad-api-improvements

Conversation

@Sebbeben
Copy link
Contributor

@Sebbeben Sebbeben commented Feb 8, 2026

Summary

Adds three improvements to the KiCad HTTP Library API ():

  • Stock quantity field — Exposes total in-stock quantity as a \ field and storage locations as . Excludes expired lots and lots with unknown quantity. Engineers can now see parts availability directly in KiCad's symbol chooser.
  • Datasheet URL resolution — The \ field now resolves to an actual datasheet file URL instead of always using the Part-DB page link. Searches attachments by type name containing "datasheet", then by attachment name, then falls back to the first PDF attachment, and finally to the Part-DB page URL.
  • HTTP cache headers — Adds \ and \ headers to all API responses. Supports conditional requests () returning \ when data hasn't changed. Categories/part lists cache for 5 minutes, part details for 1 minute.

Also fixes a pre-existing bug in \ which was actually testing Part 1 instead of Part 2.

Related issues

New fields exposed

Field Visibility Description
\ Hidden Total quantity across all valid (non-expired, known) lots
\ Hidden Comma-separated list of storage locations with stock
\ Hidden Direct link to the part's info page in Part-DB

Test plan

  • Added 14 unit tests in \ covering stock calculation (zero, single, multiple lots, expired/unknown exclusion), datasheet resolution (type name, attachment name, PDF fallback, space variant), storage locations, and field visibility
  • Added HTTP cache header tests and 304 conditional request test in - [x] Fixed \ to test actual Part 2 with EDA inheritance from category/footprint
  • Manually tested all three features on a live Part-DB instance with KiCad 9

@Sebbeben
Add stock quantity, datasheet URL, and HTTP caching to KiCad API
a40ffea 
- Add Stock field showing total available quantity across all part lots
- Add Storage Location field when parts have stored locations
- Resolve actual datasheet PDF from attachments (by type name, attachment
  name, or first PDF) instead of always linking to Part-DB page
- Keep Part-DB page URL as separate "Part-DB URL" field
- Add ETag and Cache-Control headers to all KiCad API endpoints
- Support conditional requests (If-None-Match) returning 304
- Categories/part lists cached 5 min, part details cached 1 min
@Sebbeben
Add KiCadHelper unit tests and fix PDF detection for external URLs
789f17a 
- Add comprehensive KiCadHelperTest with 14 test cases covering:
  - Stock quantity calculation (zero, single lot, multiple lots)
  - Stock exclusion of expired and unknown-quantity lots
  - Storage location display (present, absent, multiple)
  - Datasheet URL resolution by type name, attachment name, PDF extension
  - Datasheet fallback to Part-DB URL when no match
  - "Data sheet" (with space) name variant matching
- Fix PDF extension detection for external attachments (getExtension()
  returns null for external-only attachments, now also parses URL path)
@Sebbeben
Fix 304 response body, parse_url safety, and location/stock consistency
1cefffe 
- Use empty Response instead of JsonResponse(null) for 304 Not Modified
  to avoid sending "null" as response body
- Guard parse_url() result with is_string() since it can return false
  for malformed URLs
- Move storage location tracking inside the availability check so
  expired and unknown-quantity lots don't contribute locations
@Sebbeben
Fix testPartDetailsPart2 to actually test Part 2
185107f 
The test was requesting /parts/1.json instead of /parts/2.json and had
Part 1's expected data. Now tests Part 2 which inherits EDA info from
its category and footprint, verifying the inheritance behavior.
@Sebbeben
Use Symfony's built-in ETag handling for HTTP caching
02869f2 
Replace manual If-None-Match comparison with Response::setEtag() and
Response::isNotModified(), which properly handles ETag quoting, weak
vs strong comparison, and 304 response cleanup. Fixes PHPStan return
type error and CI test failures.
@codecov
Copy link

codecov bot commented Feb 8, 2026 •
edited
Loading

Codecov Report

❌ Patch coverage is 92.85714% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 54.86%. Comparing base (c2a51e5) to head (02869f2).

Files with missing lines Patch % Lines
src/Services/EDA/KiCadHelper.php 90.90% 4 Missing ⚠️
Additional details and impacted files 
@@             Coverage Diff              @@
##             master    #1232      +/-   ##
============================================
+ Coverage     54.72%   54.86%   +0.14%     
- Complexity     7918     7938      +20     
============================================
  Files           596      596              
  Lines         25468    25516      +48     
============================================
+ Hits          13937    13999      +62     
+ Misses        11531    11517      -14

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@jbtronics
Copy link
Member

jbtronics commented Feb 11, 2026

From some quick look:

  • I thing the behavior what gets exposed as datasheet URL should be configurable. A system setting that switches between yours and the old behavior would be good, as I think some people value being able to jump to Part-DB directly (and at least in my experiments the datasheet field was the only one which gets rendered as link)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Sebbeben @jbtronics