<h2>Principles of Good API Design</h2><p>A well-designed API is <strong>intuitive</strong>, <strong>consistent</strong>, and <strong>forgiving</strong>. Here are the patterns that make developers reach for your API first.</p><h3>Use Nouns, Not Verbs</h3><pre><code>GET /api/users (list)\nGET /api/users/123 (show)\nPOST /api/users (create)\nPUT /api/users/123 (update)\nDELETE /api/users/123 (destroy)</code></pre><h3>Consistent Error Responses</h3><p>Always return errors in a predictable format:</p><pre><code>{\n "message": "Validation failed",\n "errors": {\n "email": ["The email field is required."]\n }\n}</code></pre><h3>Pagination</h3><p>Never return unbounded lists. Use <em>cursor-based</em> or <em>offset-based</em> pagination:</p><ul><li><strong>Offset:</strong> Simple but slow on large datasets</li><li><strong>Cursor:</strong> Performant and consistent, preferred for feeds</li></ul><hr><h3>Versioning</h3><p>Version your API from day one. The two common approaches:</p><ol><li>URL path: <code>/api/v1/users</code></li><li>Header: <code>Accept: application/vnd.api.v1+json</code></li></ol><blockquote><p>Breaking changes should always go in a new version. Adding fields is not a breaking change.</p></blockquote>