4 Must‑Have Non‑Functional Requirements for Secure, Documented APIs

Introduction

When building an API for a client‑server application, the goal is not only to make it function correctly but also to satisfy essential non‑functional requirements that affect security, usability, and maintainability.

Four Core Non‑Functional Requirements

1. Security

API security should cover four key areas:

HTTPS/SSL certificates – Use HTTPS with a trusted SSL certificate (e.g., Let’s Encrypt) to encrypt traffic between client and server.

Cross‑origin resource sharing (CORS) – Configure CORS headers so browsers can safely request resources from different origins.

Authentication and JSON Web Tokens (JWT) – Issue JWTs after user login and verify them on each request.

Authorization and scopes – Define scopes (e.g., RESOURCE:ACTION) to limit what an authenticated client may do.

“CORS is an HTTP‑header based mechanism that allows a server to indicate which origins are permitted to load resources.” – MDN

JWT Verification Example

import jwt from 'jsonwebtoken'
export default function(req, res, next) {
  // req.headers.authorization Bearer token
  const token = extractToken(req)
  jwt.verify(token, SECRET, { algorithms: ['HS256'] }, (err, decoded) => {
    if (err) { next(err) }
    req.session = decoded
    next()
  })
}

2. Documentation

Good API documentation consists of three parts:

Getting‑started guide (README) – purpose, setup, testing, deployment.

Technical reference – detailed endpoint specifications, often using OpenAPI.

Usage guides – examples and tutorials that show real‑world scenarios.

3. Validation

Validate all incoming data (JSON payloads, query parameters, etc.) before processing. Use libraries such as Joi, Yup, or Zod, or utility functions from lodash or ramda. Validation also applies to data received from external services.

4. Testing

Testing is the primary non‑functional requirement for any API. Integration tests that simulate requests and responses are especially effective. Tools like Tape, Test‑server, and fetch‑mock enable isolated testing without relying on live back‑ends.

Conclusion

Addressing security, documentation, validation, and testing ensures that an API is reliable, safe, and easy to maintain in production. These four pillars form the foundation of a successful API strategy.