Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 30 commits into from
Oct 29, 2024
Merged
Show file tree
Hide file tree
Changes from 24 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
177f1fe
✨ New Rule - Do you know the key principles of API Design?
jeoffreyfischer Oct 25, 2024
86eaa02
Added rule to category
jeoffreyfischer Oct 25, 2024
a6be254
Auto-fix Markdown files
github-actions[bot] Oct 25, 2024
4e849f7
Update rule.md
tiagov8 Oct 25, 2024
116fe90
Update rule.md
tiagov8 Oct 25, 2024
cffbb98
Auto-fix Markdown files
github-actions[bot] Oct 25, 2024
d34f244
Update rules/key-principles-of-api-design/rule.md
jeoffreyfischer Oct 28, 2024
2cf96af
Update rules/key-principles-of-api-design/rule.md
jeoffreyfischer Oct 29, 2024
9fb5b43
Update rules/key-principles-of-api-design/rule.md
jeoffreyfischer Oct 29, 2024
e089b26
Update rules/key-principles-of-api-design/rule.md
jeoffreyfischer Oct 29, 2024
3682517
Rename rule
jeoffreyfischer Oct 29, 2024
a2f79bb
Rename category
jeoffreyfischer Oct 29, 2024
5717d80
Added SEO description
jeoffreyfischer Oct 29, 2024
ada7cf1
Edited naming - Dan comment
jeoffreyfischer Oct 29, 2024
bc67fbf
Edited pagination - Dan comment
jeoffreyfischer Oct 29, 2024
7d9898d
Edited query string - Dan comment
jeoffreyfischer Oct 29, 2024
73b0a68
Edited Security section - Dan comment
jeoffreyfischer Oct 29, 2024
6ef8ece
Moved rule to different category
jeoffreyfischer Oct 29, 2024
c6df263
Auto-fix Markdown files
github-actions[bot] Oct 29, 2024
bae09f9
Edited cross-resource- Dan comment
jeoffreyfischer Oct 29, 2024
78eb23a
Auto-fix Markdown files
github-actions[bot] Oct 29, 2024
70c519e
Added 2 extra sections - Dan comment
jeoffreyfischer Oct 29, 2024
4604bae
Auto-fix Markdown files
github-actions[bot] Oct 29, 2024
6cd3fc0
Added Daniel as an author
jeoffreyfischer Oct 29, 2024
374a3e1
Added comment and rule about versioning
jeoffreyfischer Oct 29, 2024
44e0032
Auto-fix Markdown files
github-actions[bot] Oct 29, 2024
4ab8293
Update rules/key-principles-of-rest-api-design/rule.md
jeoffreyfischer Oct 29, 2024
bae9c1d
Update rules/key-principles-of-rest-api-design/rule.md
jeoffreyfischer Oct 29, 2024
fbec695
Auto-fix Markdown files
github-actions[bot] Oct 29, 2024
2530550
Edited security comment - Luke review
jeoffreyfischer Oct 29, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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

---

Expand Down
106 changes: 106 additions & 0 deletions rules/key-principles-of-rest-api-design/rule.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
---
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
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.

## 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.
jeoffreyfischer marked this conversation as resolved.
Show resolved Hide resolved

## 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 in API design. Pass sensitive information, like access tokens, securely via headers (e.g., `Authorization: Bearer {token}`).

jeoffreyfischer marked this conversation as resolved.
Show resolved Hide resolved
Common security headers should also be considered:

* 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, aovoid 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`.
jeoffreyfischer marked this conversation as resolved.
Show resolved Hide resolved

## 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.
Loading