7.9.3: Hands On Lab Exercises

Lab: Designing RESTful APIs for a Cloud Application

Objective: Design a complete RESTful API specification for a cloud-based application.

Scenario: TaskFlow is a cloud-based project management SaaS application. You need to design the REST API that will serve both the web/mobile frontends and third-party integrations.

Core entities:

• Users (name, email, role)

• Projects (name, description, owner, members, status)

• Tasks (title, description, assignee, project, priority, status, due date)

• Comments (text, author, task, timestamp)

Instructions:

1. API Resource Design (20 min): Define the REST API endpoints for all CRUD operations on each entity. Use proper HTTP methods and URL patterns. Create a table:

   API Resources

   Method	Endpoint	Description	Request Body	Response
   GET	/api/v1/projects	List all projects	—	Array of projects
   ...	...	...	...	...

   Include at least 15 endpoints covering basic CRUD plus relationships (e.g., tasks within a project, comments on a task).

2. Request/Response Design (15 min): Design JSON request and response bodies for:

   • Creating a new project

   • Retrieving a task with its comments

   • Updating a task's status Include appropriate fields, data types, and nested objects.

3. Error Handling (10 min): Design a consistent error response format for the API. Define error responses for:

   • 400 Bad Request (validation error)

   • 401 Unauthorized

   • 403 Forbidden

   • 404 Not Found

   • 500 Internal Server Error

4. Authentication & Authorization (15 min): Design the authentication flow for the API:

   • How do users obtain access tokens?

   • How are tokens included in API requests?

   • How do you handle different permission levels (admin, project owner, team member, read-only)?

5. API Documentation (15 min): Write documentation for three of your endpoints that a third-party developer could use to integrate with TaskFlow. Include: description, URL, method, headers, request parameters, example request, example response, and possible errors.

6. SOAP vs REST Comparison (15 min): Rewrite ONE of your REST endpoints as a SOAP service definition. Compare the complexity, verbosity, and tooling requirements of both approaches.

Deliverables:

• Complete API endpoint table (15+ endpoints)

• JSON request/response examples (3 operations)

• Error response specification

• Authentication design document

• API documentation for 3 endpoints

• SOAP vs REST comparison for 1 endpoint