Oasis Accelerator Series

Build Session 4 - API Design

.

⭐ Oasis x FirstByte Trivia Night

Join us for a cozy fall evening of trivia, snacks, and friendly competition! Oasis and FirstByte are collaborating for a night of pop culture and tech trivia!

What to expect:

🧠 Trivia rounds covering tech and other categories voted on by you!

🥧 Fall treats: pumpkin pie, apple cider, and caramel apple slices

🏆 Prizes for winning teams/individuals

🤝 A great chance to meet folks from both clubs!

​

Details:

​

​

🗓️ Date: TOMORROW! (Monday, 10/19), 7 - 8:30 PM

📍 Location: Hayden Hall 012

Agenda

Designing Good APIs.

API Contracts.

API Reliability.

Designing Good APIs

.

What makes a good API?

• Intuitive: endpoints are easy to understand
• Consistent: similar operations follow similar patterns
• Predictable: requests produce expected responses
• Secure: clients only access authorized resources
• Maintainable: changes don't unnecessarily break clients

.

What makes a good API?

• Intuitive: endpoints are easy to understand
• Consistent: similar operations follow similar patterns
• Predictable: requests produce expected responses
• Secure: clients only access authorized resources
• Maintainable: changes don't unnecessarily break clients

.

Design around resources

• Represent entities as resources, such as users or orders
• Use nouns instead of action-based endpoint names
• Use plural names consistently
• Nest resources to express relationships when appropriate

.

.

HTTP Methods

• GET: retrieves a resource
• POST: creates a resource or triggers an operation
• PUT: replaces a resource
• PATCH: partially updates a resource
• DELETE: removes a resource

API Contracts

.

Clear Requests and Responses

• Keep field names consistent
• Define required and optional fields
• Use appropriate data types
• Avoid returning unnecessary information

.

Status codes

• 200 OK: Request succeeded
• 201 Created: Resource created
• 204 No Content: Succeeded without a response body
• 400 Bad Request: Invalid request
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: Access not permitted
• 404 Not Found: Resource not found
• 500 Internal Server Error: Unexpected server failure

.

Error handling

• Return a consistent error format
• Include a machine-readable error code
• Explain what went wrong
• Provide actionable validation details
• Never expose stack traces or secrets

.

Support Pagination and Filtering

• Paginate large result sets
• Support filtering by relevant fields
• Allow sorting when useful
• Set reasonable default and maximum page sizes
• Document pagination behavior

API Reliability

Idempotency

• Sending the same request twice has the same effect as sending it once
• Makes requests safe to retry when the network fails
• GET, PUT, DELETE are idempotent; POST is not
• Use an idempotency key to make POST safe

Timeouts and Retries

• Set timeouts so requests don’t hang forever
• Retry temporary failures (timeouts, 503), not client errors (400s)
• Use exponential backoff: 1s, 2s, 4s...
• Cap the number of retries

Rate Limiting

• Limit how many requests a client can make in a time window
• Protects the API from overload and abuse
• Return 429 Too Many Requests when the limit is hit
• Include a Retry-After header so clients know when to try again

Versioning

• Version the whole API from the start
• Breaking changes go in a new version
• Old clients keep using the old version

​

Questions?

Khoury Survey

Project Leads,

Let’s put this into practice 🚀

Build time 🛠️