11. Complete REST API Design

Understanding API Design: Focus on REST APIs

Introduction to API Design

• API design is crucial for backend engineers, focusing primarily on REST APIs, which are among the most widely used standards.

• Despite established standards, many new backend developers face confusion regarding URI path segments (plural vs. singular), HTTP methods (PATCH vs. PUT), and status codes.

Historical Context of Web Standards

• The video discusses the origins of web technologies initiated by Tim Berners-Lee in 1990, aimed at sharing knowledge globally.

• Key technologies introduced include URIs, HTTP protocols, HTML, web servers, and browsers—foundational elements still in use today.

Scalability Challenges and Solutions

• Rapid growth of the World Wide Web led to scalability issues that required new techniques and standards.

• Roy Fielding proposed constraints for scalable web architecture: client-server model, uniform interface, layered system, cacheable responses, statelessness, and optional code on demand.

REST Architecture Explained

• Fielding's PhD dissertation defined REST (Representational State Transfer), outlining how resources are represented and transferred between clients and servers.

• The term "REST" emphasizes three components: representation of resources in various formats (JSON/XML/HTML), state transfer of these resources during communication, and adherence to specific architectural constraints.

Designing URLs for APIs

• A typical URL structure includes scheme (HTTP/HTTPS), authority/domain name, resource/path segment indicating hierarchical relationships among resources.

• Best practices suggest using plural nouns for resource paths; e.g., /books instead of /book when fetching multiple items.

Importance of Readability in API Design

• Avoid spaces or underscores in URLs; instead use hyphens for readability. For example: harry-potter as a slug for a book title.

Concept of Idempotency in API Operations

• Idempotency refers to operations where repeated requests yield the same result; essential for ensuring consistent outcomes regardless of how many times an action is performed via an API call.

Understanding HTTP Methods in API Calls

Overview of HTTP Methods

• The discussion begins with an introduction to HTTP methods, emphasizing their importance in handling data through APIs.

• Five major HTTP methods are highlighted: GET, POST, PUT, PATCH, and DELETE. Other methods like HEAD and OPTIONS are mentioned but considered less significant for data transfer.

Characteristics of Major HTTP Methods

GET Method

• The GET method is used to retrieve information from a server and is described as idempotent; multiple calls yield the same result without altering server state.

• Even if the underlying data changes (e.g., new books added), repeated GET requests will return consistent results based on the request parameters.

PATCH and PUT Methods

• PATCH is utilized for partial updates to resources (e.g., updating specific fields), while PUT replaces the entire resource representation on the server.

• Using PATCH requires sending only modified fields, whereas PUT necessitates sending all fields of a resource for replacement.

DELETE Method

• The DELETE method is also idempotent; deleting a user once changes its state, but subsequent delete requests for the same user return an error without further side effects.

POST Method

• In contrast to other methods, POST is non-idempotent as it creates new resources. Repeated POST requests can lead to multiple entries being created in the database.

Custom Actions with POST

• The POST method serves as an open-ended option for actions that do not fit into standard CRUD operations. Examples include custom actions like sending emails.

Designing API Interfaces

Importance of Interface Design

• Before coding business logic, backend engineers should focus on designing intuitive API interfaces that adhere to RESTful standards to minimize confusion during integration.

Workflow for API Design

Identifying Resources

• Resources are defined as nouns derived from wireframes or client discussions. For example, in a project management platform context: projects, users, organizations, tasks, etc., represent key resources.

Database Schema Considerations

• After identifying resources from designs and requirements analysis, developers typically move on to database schema design before finalizing API interface design.

Action Identification

• Typical CRUD operations (Create, Read, Update, Delete) guide action identification necessary for client interactions with APIs.

Example API Design Process

Creating Organization Endpoints

• An example endpoint design process begins with creating a "GET all organizations" endpoint using appropriate URL structure and HTTP method considerations.

Implementing Create Organization Endpoint

• A "POST create organization" endpoint follows similar URL structuring principles but differentiates by using the POST method to indicate resource creation.

Creating and Managing Organizations via API

Understanding the POST Call for Organization Creation

• The payload for creating an organization must exclude server-handled fields: ID, created_at, and updated_at. These are managed on the server side.

• The client can send three fields: name, status, and description. For example, name as "Arc1", status as "active", and a sample description. All fields should be wrapped in double quotes due to JSON formatting requirements.

• Upon successful creation of an organization, the server responds with a 201 status code indicating resource creation along with the newly created entity details. This is standard behavior for POST requests.

Retrieving Created Organizations

• When retrieving organizations after creation, a 200 status code is returned if the request is successful; this indicates that data retrieval was successful rather than resource creation.

• The response includes pagination information such as total count of organizations and current page data which helps manage large datasets effectively through pagination techniques.

Pagination Explained

• Pagination is essential when dealing with large datasets to avoid overwhelming clients or servers by returning only a portion of data at once (e.g., 10 or 20 entries). This improves performance and user experience by reducing load times.

• It allows clients to request specific pages of data using parameters like limit (number of items per page) and page (which page to retrieve). Default values should be set by the server if these parameters are not provided by the client.

Implementing Sorting in List APIs

• Sorting can be implemented in list APIs using parameters such as sort_by to specify which field to sort by (e.g., name) and sort_order for ascending or descending order preferences. Default sorting should ideally be set to descending order based on creation date if no parameter is specified by the client.

Filtering Data in List APIs

• Clients may want to filter results based on certain criteria (e.g., active vs archived organizations). This can be achieved by adding filter parameters like status, allowing users to view only relevant entries based on their needs.

Updating Organizations via PATCH Requests

Best Practices for Update Operations

• PATCH requests are preferred over PUT when updating partial fields of an entity since they convey intent more clearly without requiring full entity replacement, which aligns better with single-page application practices where JSON-heavy interactions occur frequently.

Fetching Single Organization Details

• To fetch details about a single organization post-update, a GET request is made using its unique ID within the URL path structure similar to other CRUD operations ensuring consistency across API endpoints for different methods (GET, PATCH, DELETE).

Deleting Organizations

Handling Deletion Responses

• A DELETE operation typically returns a 204 No Content status code upon success indicating that while the deletion was successful there’s no content available in response; this differs from other operations where data might still need to be sent back even after modification or retrieval actions have been performed successfully.

Error Handling in API Calls

• If attempting to access an organization that has been deleted via its ID results in a 404 Not Found error indicating that requested resource does not exist anymore; however, list API calls return empty arrays instead of errors when no matching records are found—this distinction helps maintain clarity between individual resource requests versus bulk listings where absence doesn’t imply failure but simply lack of available data at that moment.

Understanding Custom Actions in API Design

Overview of CRUD Operations

• The discussion begins with a recap of CRUD operations: Create, Read (Get and List), Update, and Delete. These are foundational to typical API design.

• It is emphasized that not all server actions fit neatly into these categories; some require custom actions.

Defining Custom Actions

• A custom action is described as an operation that does not align with standard CRUD methods, such as archiving an organization.

• Archiving involves changing the status of an organization but requires additional server-side operations beyond a simple update.

Complexity of Archiving

• When archiving an organization, multiple related tasks must be executed, such as notifying users or deleting associated projects.

• This complexity necessitates treating the archive operation as a custom action rather than just a status update.

Implementing Custom Actions in APIs

• For actions outside CRUD flows, POST requests are recommended to construct API calls for executing custom actions on the server.

• An example is provided where the endpoint for archiving an organization is structured hierarchically to reflect its relationship within the API.

Response Codes and Expectations

• Upon executing the archive request, a 200 response code indicates success despite using POST, which typically suggests resource creation.

• It's important not to assume every POST call will return a 201 response; custom actions may yield different codes based on their nature.

Transitioning from Organizations to Projects in API Design

Structuring Project Endpoints

• The speaker transitions to designing project endpoints after completing those for organizations.

• A new folder structure is created for better management of project-related endpoints within the API client tool Insomnia.

Creating New Projects

• The process for creating projects follows similar patterns established earlier: using plural forms and adhering to JSON standards in payload structures.

• Key fields like name, organization ID, status, and description are included in the JSON payload while ensuring camel case formatting throughout.

Listing Projects and Pagination

• A GET request allows listing all projects stored in the database. Pagination parameters can be applied to manage data retrieval effectively.

• Consistency across query parameters and JSON payload formats between different resources (organizations vs. projects) is stressed for ease of integration by clients.

Best Practices for API Design

Importance of Consistency

• Maintaining consistent naming conventions across APIs prevents confusion during integration by frontend engineers who rely on established patterns.

Designing Intuitive APIs

• Providing interactive documentation (e.g., Swagger tools), intuitive routes, and consistent behavior enhances user experience when integrating APIs.

Default Values and Avoiding Abbreviations

• Setting sensible defaults (like active status upon creation unless specified otherwise), helps streamline client interactions with APIs.

Final Thoughts on Effective API Development

• Emphasizing thoughtful design over immediate coding ensures that APIs meet user needs effectively while minimizing guesswork during integration.