XS✔ ◾ ✨ New Rule - Do you know the key principles of API Design? (#9488)

* ✨ New Rule - Do you know the key principles of API Design?

* Added rule to category

* Auto-fix Markdown files

* Update rule.md

* Update rule.md

* Auto-fix Markdown files

* Update rules/key-principles-of-api-design/rule.md

Co-authored-by: Brady Stroud [SSW] <[email protected]>

* Update rules/key-principles-of-api-design/rule.md

Co-authored-by: Daniel Mackay [SSW] <[email protected]>

* Update rules/key-principles-of-api-design/rule.md

Co-authored-by: Daniel Mackay [SSW] <[email protected]>

* Update rules/key-principles-of-api-design/rule.md

Co-authored-by: Daniel Mackay [SSW] <[email protected]>

* Rename rule

* Rename category

* Added SEO description

* Edited naming - Dan comment

* Edited pagination - Dan comment

* Edited query string - Dan comment

* Edited Security section - Dan comment

* Moved rule to different category

* Auto-fix Markdown files

* Edited cross-resource- Dan comment

* Auto-fix Markdown files

* Added 2 extra sections - Dan comment

* Auto-fix Markdown files

* Added Daniel as an author

* Added comment and rule about versioning

* Auto-fix Markdown files

* Update rules/key-principles-of-rest-api-design/rule.md

Co-authored-by: Daniel Mackay [SSW] <[email protected]>

* Update rules/key-principles-of-rest-api-design/rule.md

Co-authored-by: Daniel Mackay [SSW] <[email protected]>

* Auto-fix Markdown files

* Edited security comment - Luke review

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Tiago Araújo [SSW] <[email protected]>
Co-authored-by: Brady Stroud [SSW] <[email protected]>
Co-authored-by: Daniel Mackay [SSW] <[email protected]>

categories/software-engineering/rules-to-better-web-api-rest.md

@@ -14,6 +14,7 @@ index:
 - do-you-return-detailed-error-messages
 - do-you-return-the-correct-response-code
 - use-fluent-validation
+- key-principles-of-rest-api-design
 
 ---
 

rules/key-principles-of-rest-api-design/rule.md

@@ -0,0 +1,115 @@
+---
+seoDescription: Learn the essential principles of REST API design to create APIs that are clear, reliable, and secure. Discover tips on naming conventions, idempotency, versioning, pagination, sorting, security, and more to build developer-friendly interfaces that foster trust and ease of use.
+type: rule
+archivedreason:
+title: Do you know the key principles of REST API Design?
+guid: f847325c-97a5-48e7-a2ce-8e56b33512d1
+uri: key-principles-of-rest-api-design
+created: 2024-10-25T14:38:33.0000000Z
+authors: 
+  - title: Jeoffrey Fischer
+    url: https://ssw.com.au/people/jeoffrey-fischer
+  - title: Daniel Mackay
+    url: https://www.ssw.com.au/people/daniel-mackay/
+related:
+- choose-the-right-api-tech
+- do-you-know-the-common-design-principles-part-1
+- do-you-provide-versioning
+redirects: []
+
+---
+
+REST APIs are everywhere in our daily lives—from social media updates and online shopping to weather forecasts and GPS navigation. These interfaces allow different applications to connect seamlessly, providing the backbone for countless modern conveniences.
+
+Building a high-quality API means adhering to best practices that enhance clarity, reliability, and security, creating a more consistent experience for developers and users.
+
+<!--endintro-->
+
+`youtube: https://youtu.be/_gQaygjm_hg`
+**Video: Good APIs Vs Bad APIs: 7 Tips for API Design (6 min)**
+
+## Tip \#1 - Use clear naming  
+
+Choose descriptive, intuitive names for endpoints and parameters to improve readability. Adhere to REST conventions, using nouns and verbs logically (e.g., `/api/users` for accessing user data, `/api/users/{id}` for specific user information). Endpoints should also use plurals. i.e `/api/users` instead of `/api/user`. This provides a much more consistent API structure when querying both collections and single entities.
+
+Clear naming simplifies usage and reduces misunderstandings.  
+
+## Tip \#2 - Ensure reliability through idempotency  
+
+To avoid unintended actions from repeated requests, design POST, PUT, and DELETE operations as idempotent, where repeating an action yields the same result as performing it once.
+
+For example, if a DELETE request removes a record, re-sending it should not throw errors if the record is already deleted.
+
+This prevents accidental duplicate data processing.  
+
+## Tip \#3 - Implement versioning  
+
+Introduce versioning from the start (e.g., `/v1/resource`) to maintain backward compatibility when updating the API.
+
+Versioning helps users manage changes without breaking existing implementations, allowing them to adopt new features gradually.  
+
+There are 3 common ways to implement versioning:  
+
+* Route  
+* Query String  
+* Header  
+
+For more details, you can check this rule: [https://www.ssw.com.au/rules/do-you-provide-versioning/](Do you provide versioning?).  
+
+## Tip \#4 - Add pagination for responses  
+
+For endpoints that return lists, apply pagination to prevent overwhelming the client with too much data.
+
+When paging parameters are omitted from the request, the API should apply some sensible defaults (e.g. page 1, 50 records).
+
+Use query parameters like `?page=` and `?limit=` to specify page numbers and size, offering a more manageable data experience while improving performance.  
+
+## Tip \#5 - Use clear query strings for sorting  
+
+When supporting sorting, apply clear query strings (e.g., `?sortBy=name&order=asc`). Query params should generally be optional making the API easier to consume.
+
+Consistent sorting parameters allow developers to retrieve and organize data efficiently and minimize confusion in handling API responses.  
+
+## Tip \#6 - Security should not be an afterthought
+
+Security is paramount when building REST APIs. Most REST APIs are hosted online, and you don't want to rely on "security via obscurity". Ensure you spend time hardening your surface area.  
+
+Common sense approaches include protecting your endpoints via short-lived access tokens (even for seemingly benign functionality), as well as your typical security headers such as:  
+
+* Content-Security-Policy (CSP)  
+* Strict-Transport-Security (HSTS)  
+* X-Content-Type-Options  
+* X-Frame-Options  
+
+Enforce HTTPS for encrypted communication and consider OAuth for user authentication and authorization, protecting against unauthorized access.  
+
+## Tip \#7 - Keep cross-resource references simple
+
+For APIs that reference multiple resources (e.g., `userId` in a post endpoint), keep relationships simple to prevent over-complicating endpoints.
+
+Provide clear references or IDs rather than nested data whenever possible to keep API responses readable and easy to follow.  
+
+For example, avoid using messy query patameters such as `api/products?user_id=123&product_id=321`. Instead, use clearly defined endpoints like `api/users/123/products/321`.
+
+## Extra tip - Rate limiting  
+
+Implement rate limiting to control the number of requests per user within a time frame, protecting the API from abuse and ensuring fair resource usage.
+
+Provide appropriate status codes and messages (e.g., `HTTP 429`) when limits are reached to inform users clearly.
+
+## Extra tip - Caching
+
+Implement caching for frequently requested data to reduce server load and response times, enhancing the user experience. Cache static data responses at the client or server side where appropriate, especially for resources that don't change frequently.  
+
+Use HTTP cache headers like `Cache-Control` and `ETag` to guide clients on when to use cached data or refresh it, balancing speed and data freshness.  
+
+## Extra tip - Compression
+
+Enable compression for API responses, especially for large data payloads, to reduce bandwidth and improve loading times.  
+
+Use GZIP or Brotli compression formats, which are widely supported and effective in reducing data sizes.  
+
+---
+
+Following these guidelines ensures your API is well-structured, secure, and developer-friendly.
+Thoughtful API design not only improves functionality but also fosters trust and ease of use for everyone who interacts with it.