API & Web Engineering

REST (Representational State Transfer) models an API as a set of resources, each addressable by a URL, manipulated through standard HTTP methods (GET, POST, PUT, DELETE, and so on). OpenAPI is the dominant specification format for documenting a REST API's contract — every endpoint, its parameters, request and response bodies (typically described using JSON Schema), and possible status codes — in a single machine-readable document that can generate documentation, client code, and validation logic.

An OpenAPI document is only useful if it's actually internally consistent and accurate: a contract with contradictory type definitions, undefined references, or missing required fields will produce generated clients and documentation that don't match the real API's actual behavior. Validating a contract catches structural problems in the specification itself, independent of whether the running API actually implements it correctly.

GraphQL takes a different approach entirely: rather than many resource-specific endpoints, a GraphQL API exposes a single endpoint and a strongly-typed schema, and clients send queries specifying exactly which fields of which types they want returned. This avoids both over-fetching (REST returning more fields than a client needs) and under-fetching (needing multiple REST calls to assemble one view), at the cost of a more complex server-side query execution model.

Curl is the lingua franca for describing an HTTP request in documentation and bug reports precisely because it's a single, copy-pasteable command — but that same portability means a curl command often needs to be translated into whatever language a specific client, test suite, or automation script is actually written in.

A common workflow starts with a curl command copied from API documentation or a colleague's bug report. Use the Curl Command Builder to construct or modify one with the correct headers, method, and body for what you're testing, then the Curl → Fetch Converter or Curl → Python Requests Converter to translate it directly into the language your actual client code or test script uses, rather than hand-translating flags and headers yourself.

When working with an API's OpenAPI contract, use the OpenAPI Validator to confirm the specification document itself is structurally valid before relying on it to generate documentation or client code — a broken contract produces broken generated artifacts regardless of whether the running API behaves correctly.

Before deploying a new version of an API, use the OpenAPI Diff Checker to compare the previous contract against the new one and catch breaking changes — a removed field, a newly-required parameter, a changed response type — before they reach consumers who built against the old contract.

For a GraphQL API, use the GraphQL Query Explorer to browse the schema and test queries interactively against a real endpoint, and the GraphQL Query Formatter to clean up a minified or inconsistently-formatted query pulled from a log or a colleague's message before reviewing or reusing it.

Mistake: hand-translating a curl command's flags into another language and missing a header or misquoting an argument with special characters — a small translation error that then takes far longer to debug in the target language than the original conversion would have taken with a dedicated converter.

Mistake: treating an OpenAPI contract as documentation only, never actually validating it — a specification with structural errors can still render as plausible-looking documentation while producing broken generated clients or SDKs.

Mistake: shipping an API change without diffing the old and new OpenAPI contracts, missing that a field consumers depend on was silently removed or its type was changed in a way that breaks existing integrations.

Troubleshooting: if a GraphQL query returns unexpected null values instead of an error, check whether the field is actually nullable in the schema first — GraphQL returns null for a field that resolved to no data, which looks identical to a field that simply wasn't populated unless you check the schema's nullability for that specific field.

Troubleshooting: if a translated fetch or Python requests call behaves differently from the original curl command, check for a default header curl sets automatically (such as Content-Type for a JSON body) that the translation may not have carried over explicitly.

The OpenAPI Specification (formerly Swagger) is maintained by the OpenAPI Initiative and is the dominant standard for describing REST API contracts; it uses JSON Schema, covered in more depth in the JSON Workshop hub, as its type-description language.

GraphQL itself is defined by the GraphQL Specification, maintained by the GraphQL Foundation, independently of any single implementation or server library.

RFC 7807 defines a standard 'Problem Details' JSON format for HTTP API error responses, worth adopting in an OpenAPI contract's error schemas for consistency across endpoints rather than inventing a bespoke error shape per API.

The underlying HTTP methods, status codes, and header semantics that both REST and curl commands operate on are defined by RFC 9110 — see the HTTP & Web Protocols hub for that layer specifically; this hub builds on it rather than re-specifying it.

Choose REST with an OpenAPI contract when your API models a relatively fixed, well-understood set of resources, when broad tooling compatibility (API gateways, generated SDKs, documentation platforms) matters, or when caching individual resource responses via standard HTTP caching is valuable. Choose GraphQL when clients have genuinely varied data needs per request (a mobile client needing fewer fields than a web dashboard), or when reducing round-trips for deeply nested data matters more than the added complexity of a query-execution layer.

For contract validation, validate structurally (does the OpenAPI document itself parse and conform to the spec) as a baseline in every workflow; add contract diffing specifically at any point where an API version changes and existing consumers need to keep working without modification.

When choosing whether to hand-write a curl-to-code translation or use a converter, the converter is almost always the better choice for anything beyond a trivially simple request — the time saved compounds every time the underlying curl command changes and needs re-translating.

A GraphQL query's shape directly determines what's returned: requesting only the fields a specific view actually needs, rather than an entire object graph, is the core discipline that makes GraphQL's efficiency advantage over REST actually materialize in practice rather than just in theory.

Use the GraphQL Query Explorer against a real schema to discover available types and fields interactively, which is generally faster and more accurate than reading through separate schema documentation, especially for a schema that's evolved over time and may not be perfectly documented externally.

Formatting matters more for GraphQL queries than it might first appear: a deeply nested query with inconsistent indentation is genuinely hard to review for correctness, since matching opening and closing braces visually is how most people actually verify a complex nested selection is structured the way they intended. Use the GraphQL Query Formatter before committing a complex query to a codebase or sharing it for review.

Mutations (GraphQL's mechanism for writes, as opposed to queries for reads) follow the same syntax family as queries but carry side effects — treat a formatted or explored mutation with the same caution you'd apply to any write operation, since exploring a query against a live schema is safe, but running an unfamiliar mutation against a live system is not.