API Documentation Best Practices for OpenAPI SpecsMost API docs are generated from an OpenAPI file, so better docs start with a better spec. Here is what to write in it, with a scored before and after.LatestAPI documentation7 min readRead the guide
- API Naming Conventions for Paths, Fields, and HeadersA naming cheat sheet for REST APIs, with the reasoning behind each rule and a scored before-and-after spec.REST API7 min read
- API Pagination Best Practices: Offset, Cursor, KeysetOffset pagination is easy until rows move or the offset gets large. Here is how keyset and cursor pagination fix that, and how to document them.REST API7 min read
- API Quality Checklist: Seven Checks Behind a Design ScoreA design-review checklist for paths, methods and responses, tested against a real scoring engine with a before and after spec.API quality7 min read
- API Rate Limiting Algorithms, 429 Responses and HeadersHow token bucket, fixed window, sliding window and leaky bucket behave, and how to tell clients they hit the limit.API performance7 min read
- API Security Best Practices Mapped to the OWASP Top 10The ten OWASP API risks, the control for each, and which of those controls you can see in an OpenAPI spec.API security6 min read
- API Testing Best Practices: What to Test and WhereA testing strategy for HTTP APIs: which layer catches which bug, where each suite runs in CI, and how to keep test data and auth tests reliable.API testing9 min read
- API Versioning Strategies: URI, Header, or Media TypePick where the version goes, write down which changes force a new one, and plan how the old one retires.API versioning7 min read
- Common OpenAPI Errors and How to Fix ThemThe error messages people hit when an OpenAPI or Swagger file fails to parse or validate, what each one means, and the fix.OpenAPI7 min read
- How to Validate an OpenAPI or Swagger Spec FileSpec validation has layers. Here is what each one checks, which tools run them, and the bugs that pass all of them.OpenAPI6 min read
- OpenAPI Best Practices for Writing the Spec FileHow to write an OpenAPI document that code generators, docs portals, and linters can use, with a before and after example.OpenAPI7 min read
- OpenAPI Response Design: Status Codes, Nullable, ErrorsHow to model responses in an OpenAPI document so generated clients and readers know exactly what each status code returns.OpenAPI9 min read
- REST API Design Best Practices: Resources and MethodsModel nouns, let the HTTP method carry the action, and design every write for retries. A sample API goes from 55.3 to 100.REST API8 min read
- REST API Error Handling: Status Codes and Problem DetailsPick the status code first, then return one problem details body that clients can branch on. Worked example with a scored spec.API errors8 min read
- Swagger vs OpenAPI: Names, Versions, and DifferencesSwagger 2.0 and OpenAPI 2.0 are the same spec. Here is what changed in 3.0 and 3.1, with one API written in both formats.OpenAPI6 min read
- Generate API Test Cases from an OpenAPI SpecEvery required field, type, length limit and enum in a spec is a test waiting to be written. Here is how to derive them.API testing5 min read
- How to Get the OpenAPI JSON from a Swagger UI PageSwagger UI only displays a spec. Here is how to find the JSON or YAML file it loads, framework by framework.OpenAPI5 min read
- Validate API Responses Against Your OpenAPI SchemaA valid spec does not mean the API follows it. Here is how to check real responses against the schema, with a worked example.API testing5 min read