home / skills / secondsky / claude-skills / api-response-optimization

api-response-optimization skill

safe

/plugins/api-response-optimization/skills/api-response-optimization

This skill reduces API payloads, enables efficient caching, and applies compression to improve response times and bandwidth usage.

npx playbooks add skill secondsky/claude-skills --skill api-response-optimization

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: api-response-optimization
description: Optimizes API performance through payload reduction, caching strategies, and compression techniques. Use when improving API response times, reducing bandwidth usage, or implementing efficient caching.
---

# API Response Optimization

Reduce payload sizes, implement caching, and enable compression for faster APIs.

## Sparse Fieldsets

```javascript
// Allow clients to select fields: GET /users?fields=id,name,email
app.get('/users', async (req, res) => {
  const fields = req.query.fields?.split(',') || null;
  const users = await User.find({}, fields?.join(' '));
  res.json(users);
});
```

## HTTP Caching Headers

```javascript
app.get('/products/:id', async (req, res) => {
  const product = await Product.findById(req.params.id);
  const etag = crypto.createHash('md5').update(JSON.stringify(product)).digest('hex');

  if (req.headers['if-none-match'] === etag) {
    return res.status(304).end();
  }

  res.set({
    'Cache-Control': 'public, max-age=3600',
    'ETag': etag
  });
  res.json(product);
});
```

## Response Compression

```javascript
const compression = require('compression');

app.use(compression({
  filter: (req, res) => {
    if (req.headers['x-no-compression']) return false;
    return compression.filter(req, res);
  },
  level: 6  // Balance between speed and compression
}));
```

## Performance Targets

| Metric | Target |
|--------|--------|
| Response time | <100ms (from 500ms) |
| Payload size | <50KB (from 500KB) |
| Server CPU | <30% (from 80%) |

## Optimization Checklist

- [ ] Remove sensitive/unnecessary fields from responses
- [ ] Implement sparse fieldsets
- [ ] Add ETag/Last-Modified headers
- [ ] Enable gzip/brotli compression
- [ ] Use pagination for collections
- [ ] Eager load to prevent N+1 queries
- [ ] Monitor with APM tools

## Best Practices

- Cache immutable resources aggressively
- Use short TTL for frequently changing data
- Invalidate cache on writes
- Compress responses >1KB
- Profile before optimizing

Overview

This skill optimizes API performance by reducing payloads, applying caching strategies, and enabling response compression. It provides practical techniques like sparse fieldsets, HTTP caching headers, and gzip/brotli compression to lower latency and bandwidth. The goal is measurable improvement in response time, payload size, and server load for production APIs.

How this skill works

The skill inspects API responses and suggests or applies changes to reduce unnecessary data, such as removing sensitive fields and implementing sparse fieldsets. It adds HTTP caching (ETag, Last-Modified, Cache-Control) to avoid redundant work and configures compression middleware with sensible defaults. It also recommends pagination, eager loading to avoid N+1 queries, and monitoring targets to validate improvements.

When to use it

When API response times are high and you need tangible latency reductions.
When bandwidth costs are significant or clients see large payloads.
When you want to add or improve caching to reduce repeated processing.
When serving large collections without pagination or sparse selection.
Before scaling infrastructure — to get more capacity from existing servers.

Best practices

Remove sensitive and unnecessary fields from responses to reduce payload and exposure.
Expose sparse fieldsets so clients request only the fields they need.
Set ETag or Last-Modified plus Cache-Control for immutable resources.
Enable gzip/brotli compression for responses larger than ~1KB and tune compression level for CPU tradeoffs.
Use pagination and server-side cursors for large collections and eager load relations to avoid N+1 queries.
Monitor with APM and define performance targets before and after changes.

Example use cases

A product API adds ETag and returns 304 responses for unchanged resources to cut server load.
A user endpoint implements ?fields=id,name,email to deliver minimal payloads for mobile clients.
Enabling compression on HTML and JSON responses to reduce bandwidth and improve page load times.
Applying pagination and eager loading to a social feed to eliminate N+1 queries and reduce response size.
Setting short TTLs for dynamic data and long TTLs for immutable assets to balance freshness and cache hit rate.

FAQ

Will compression always improve latency?

Not always — compression reduces transfer time but increases CPU. Test different compression levels and enable it for payloads that benefit most, typically >1KB.

When should I use ETag vs Last-Modified?

ETag is preferred for precise change detection; Last-Modified is simpler but less accurate for small or frequent updates. Use ETag for complex objects.