API Client

This project provides a TypeScript-based, reusable API client designed to interact with REST APIs, such as JSONPlaceholder. The client supports flexible filtering, sorting, and pagination, with optional authentication, making it adaptable for various resources.

Table of Contents

• Features
• Getting Started
• Installation
• Usage
  • Basic API Call
  • Using Filters and Options
  • Making Multiple Requests
• Project Structure
• Testing
• Contributing
• Husky Integration

Features

• Generic API Client: Provides a reusable apiClient function for making HTTP requests with optional authentication.
• Filtering and Pagination: Allows for advanced filtering, sorting, and pagination options.
• Concurrent Requests: Supports making multiple requests simultaneously.
• Error Handling: Built-in error handling and logging for failed requests.
• TypeScript Support: Strongly typed for predictable, safe API interactions.

Getting Started

To use this API client, you need to have Node.js and npm installed. This project is configured to be used in a Node or browser-based JavaScript/TypeScript environment.

Installation

1. Clone the repository:

   git clone https://github.com/your-username/api-client.git
   cd api-client

2. Install dependencies:

   npm install

3. Build the TypeScript files:

   npm run build

Usage

Basic API Call

The apiClient function allows you to make an API call with optional authentication.

Example: Fetch a User

import { apiClient } from "./apiClient";

async function fetchUser() {
  const user = await apiClient<User>("/users/1");
  console.log(user);
}

fetchUser();

Using Filters and Options

The fetchFilteredData function allows you to fetch resources with optional filters, sorting, and pagination.

Example: Fetch Users with Filters

import fetchFilteredData from "./fetchFilteredData";

async function fetchFilteredUsers() {
  const users = await fetchFilteredData<User>(
    "users",
    { name_like: "Lea" },
    { sortBy: "name", order: "asc", limit: 5 },
  );
  console.log(users);
}

fetchFilteredUsers();

Making Multiple Requests

The fetchMultipleResources function allows you to perform multiple API requests concurrently and returns all results in a single call.

Example: Fetch Users and Posts Simultaneously

import fetchMultipleResources from "./fetchMultipleResources";

async function fetchUsersAndPosts() {
  const requests = [
    { resource: "users", filters: { name_like: "Lea" }, options: { limit: 5 } },
    {
      resource: "posts",
      filters: { userId: 1 },
      options: { sortBy: "id", order: "desc" },
    },
  ];

  const [users, posts] = await fetchMultipleResources(requests);
  console.log("Users:", users);
  console.log("Posts:", posts);
}

fetchUsersAndPosts();

Project Structure

The project follows a modular structure to organize source code, configuration, and tests effectively.

/project-root
├── /src
│   ├── /services                  # Contains the API client and service functions
│   │   ├── apiClient.ts           # Main API client function for making requests
│   │   └── userService.ts         # User-related API requests
│   ├── /types                     # TypeScript type definitions and interfaces
│   └── /tests                     # Unit and integration tests
├── README.md                      # Project documentation
├── tsconfig.json                  # TypeScript configuration file
└── package.json                   # Project metadata and dependencies

Explanation of Key Files

• apiClient.ts: Core API client function for sending HTTP requests with optional authentication support.
• userService.ts: Provides reusable functions for managing user-related API requests, including fetching, creating, updating, and deleting users.
• tests: Contains Jest or Postman test files to verify API client functionality.

Testing

Running Tests with Jest

The API client can be tested using Jest. Tests cover the apiClient, fetchFilteredData, and fetchMultipleResources functions to ensure they handle different API responses and errors correctly.

1. Install Jest:

   npm install --save-dev jest

2. Run Tests:

   npm test

Running Tests with Postman and Newman

1. Import Postman Collection: Import the collection to Postman and set up any necessary environment variables.
2. Run Tests with Newman:

   newman run postman-collection.json -e postman-environment.json

Contributing

Contributions are welcome! If you have suggestions, bug reports, or want to add features, feel free to open an issue or submit a pull request.

1. Fork the repository.
2. Create a new branch with a descriptive name.
3. Make changes and commit with clear, concise commit messages.
4. Push your branch and open a pull request.

Husky Integration

This project includes Husky to automate testing on every commit.

How it Works

• Husky is configured to run npm test automatically whenever you make a git commit.
• This ensures that all tests pass before the code is committed, helping to maintain code quality and prevent errors from being introduced.

Setting up Husky

If you need to reinstall Husky or modify its configuration, refer to the Husky documentation for more details on how to customize pre-commit hooks.

Running Tests Manually

In addition to the automated testing, you can always run tests manually by executing:

npm test

With this setup, code quality is enforced through continuous testing with each commit.