What is API response optimization?

It speeds up APIs by reducing payload size, leveraging caching, and enabling compression to lower bandwidth and latency.

How do I decide when to compress?

Compress when responses are larger than about 1KB and the CPU cost is acceptable; balance gzip vs Brotli based on payload and server resources.

What should I monitor after implementing these changes?

Monitor response time, payload size, cache hit rate, and CPU usage using APM tools to ensure gains and identify bottlenecks.

api-response-optimization

Scanned

npx machina-cli add skill secondsky/claude-skills/api-response-optimization --openclaw

Files (1)

SKILL.md

2.0 KB

API Response Optimization

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

Sparse Fieldsets

// 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

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

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

Source

git clone https://github.com/secondsky/claude-skills/blob/main/plugins/api-response-optimization/skills/api-response-optimization/SKILL.md

View on GitHub

Overview

API Response Optimization reduces payload sizes, implements caching headers, and enables compression to accelerate APIs. It helps lower bandwidth, improve latency, and scale by reusing cached responses and delivering only necessary data.

How This Skill Works

The approach uses sparse fieldsets to let clients select required fields, adds HTTP caching headers (ETag/Last-Modified) for conditional requests, and enables response compression to shrink payloads. It also aligns with performance targets and a practical optimization checklist to guide implementation.

When to Use It

When API responses include large payloads and bandwidth is a bottleneck.
When you want to speed up responses by leveraging caching and conditional requests.
When serving collections or lists and you need to avoid sending excessive data via pagination.
When clients can accept compressed payloads and you aim to reduce bandwidth (gzip/Brotli).
When you want to enforce best practices and monitor performance with instrumentation.

Quick Start

Step 1: Enable sparse fieldsets by parsing req.query.fields and selecting only requested fields in the database query.
Step 2: Add HTTP caching headers (ETag/Cache-Control) and implement conditional responses on the server.
Step 3: Install and configure a compression middleware (e.g., gzip/Brotli) with a threshold that skips very small payloads.

Best Practices

Remove sensitive/unnecessary fields from responses
Implement sparse fieldsets to prune payloads
Add ETag/Last-Modified headers to enable conditional requests
Enable gzip or Brotli compression for larger responses
Use pagination for collections and profile before optimizing

Example Use Cases

GET /users?fields=id,name,email returns only the selected fields to reduce payload.
GET /products/:id uses an ETag to return 304 if the product has not changed.
Enable response compression for API responses to significantly reduce transfer sizes.
Paginate large collections to deliver manageable payloads per request.
Audit and tune caching strategy with APM tools to maximize hit rates and minimize latency.

Frequently Asked Questions

Add this skill to your agents