jsonplaceholder-API-client

This package is a TypeScript-first wrapper around the JSONPlaceholder fake REST API. It provides clean, predictable helper functions for working with common resources such as posts, comments, albums, photos, todos, and users, covering the full CRUD surface (GET, POST, PUT, PATCH, DELETE).

🌱 The goal of this library is not to replace JSONPlaceholder itself, but to offer a Developer-Friendly SDK with consistent response shapes, sensible defaults, and strong TypeScript typing — making it useful for learning, prototyping, demos, and testing frontend or SDK patterns.

📻 Beta Release

To encourage developers to download and utilize this package that is made available for your benefit. Additionally, you can post feedback on any issues you encounter so that the needed corrections can be done. Official release will be announced in sometime.

📦 Installation

npm install --save jsonplaceholder-api-client

👁 Quick Start

/* node modules */
import { getAllPosts } from 'jsonplaceholder-api-client';

/* fn */
async function quickStart() {
  const response = await getAllPosts();
  console.log(response);
}

/* call */
await quickStart();

/* Sample Response Schema
{
  code: "api-ok",
  message: "No error encountered",
  payload: ...
}
*/

🎲 Features

1. Built with strong TypeScript typings from the ground up.
2. Full REST surface for common JSONPlaceholder resources: GET, POST, PUT, PATCH and DELETE.
3. Uniform response structures to simplify error handling and data access.
4. ID-based fetches normalize empty API responses, making missing resources easy to handle.
5. Clean, intention-revealing functions.
6. Uses the native fetch API without adding unnecessary runtime dependencies.
7. Designed for demos, tutorials, SDK experiments and frontend testing.

📖 What is JSONPlaceholder?

JSONPlaceholder is a free, public fake REST API that provides realistic but non-persistent data for common resources such as posts, comments, users, albums, photos, and todos. This is widely used by developers to practice working with REST APIs.

💡 Why This Exists?

JSONPlaceholder is an excellent fake REST API, but using it directly often means repeating the same boilerplate: manual fetch calls, ad-hoc response handling, loose typing, and inconsistent patterns across resources.
This package exists to solve that by providing:

1. Strong TypeScript typings for all resources and operations
2. Consistent, predictable response shapes across every endpoint
3. Clear, intention-revealing helper functions instead of raw HTTP calls
   The goal is not abstraction for abstraction’s sake, but to make working with JSONPlaceholder feel more structured, expressive, and developer-friendly — especially for learning, prototyping, demos, and SDK experimentation.

💻 Usage

📁 Resource Name: Albums

1. Get All Albums

import { getAllAlbums } from 'jsonplaceholder-api-client';
const response = await getAllAlbums();
/* Returns an array of album objects */

2. Get Album By ID

import { getAlbumById } from 'jsonplaceholder-api-client';
const response = await getAlbumById({ id: number });
/* If the album does not exist, album is returned as null */

3. Create Album

import { createNewAlbum } from 'jsonplaceholder-api-client';
const response = await createNewAlbum({
  title: string,
  userId: number,
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

4. Update Album

import { updateAlbum } from 'jsonplaceholder-api-client';
const response = await updateAlbum({
  id: number,
  data: { id: number, title: string, userId: number },
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

5. Partial Update Album

import { updateAlbumPartial } from "jsonplaceholder-api-client";
const response = await updateAlbumPartial({
  id: number,
  data: { title?: string, userId?: number }
});
/* Need to give atleast 1 of the data fields. */
/* Changes are not persisted (JSONPlaceholder behavior). */

6. Delete Album

import { deleteAlbum } from 'jsonplaceholder-api-client';
const response = await deleteAlbum({ id: number });
/* Mock delete endpoint. Changes are not persisted (JSONPlaceholder behavior). */

📁 Resource Name: Comments

1. Get All Comments

import { getAllComments } from 'jsonplaceholder-api-client';
const response = await getAllComments();
/* Returns an array of comment objects */

2. Get Comment By ID

import { getCommentById } from 'jsonplaceholder-api-client';
const response = await getCommentById({ id: number });
/* If the comment does not exist, comment is returned as null */

3. Create Comment

import { createNewComment } from 'jsonplaceholder-api-client';
const response = await createNewComment({
  postId: number,
  name: string,
  email: string,
  body: string,
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

4. Update Comment

import { updateComment } from 'jsonplaceholder-api-client';
const response = await updateComment({
  id: number,
  data: {
    id: number,
    postId: number,
    name: string,
    email: string,
    body: string,
  },
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

5. Partial Update Comment

import { updateCommentPartial } from "jsonplaceholder-api-client";
const response = await updateCommentPartial({
  id: number,
  data: {postId?: number, name?: string, email?: string, body?: string}
});
/* Need to give atleast 1 of the data fields. */
/* Changes are not persisted (JSONPlaceholder behavior). */

6. Delete Comment

import { deleteComment } from 'jsonplaceholder-api-client';
const response = await deleteComment({ id: number });
/* Mock delete endpoint. Changes are not persisted (JSONPlaceholder behavior). */

📁 Resource Name: Photos

1. Get All Photos

import { getAllPhotos } from 'jsonplaceholder-api-client';
const response = await getAllPhotos();
/* Returns an array of photo objects */

2. Get Photo By ID

import { getPhotoById } from 'jsonplaceholder-api-client';
const response = await getPhotoById({ id: number });
/* If the photo does not exist, photo is returned as null */

3. Create Photo

import { createNewPhoto } from 'jsonplaceholder-api-client';
const response = await createNewPhoto({
  albumId: number,
  title: string,
  url: string,
  thumbnailUrl: string,
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

4. Update Photo

import { updatePhoto } from 'jsonplaceholder-api-client';
const response = await updatePhoto({
  id: number,
  data: {
    id: number,
    albumId: number,
    title: string,
    url: string,
    thumbnailUrl: string,
  },
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

5. Partial Update Photo

import { updatePhotoPartial } from "jsonplaceholder-api-client";
const response = await updatePhotoPartial({
  id: number,
  data: { albumId?: number, title?: string, url?: string, thumbnailUrl?: string }
});
/* Need to give atleast 1 of the data fields. */
/* Changes are not persisted (JSONPlaceholder behavior). */

6. Delete Photo

import { deletePhoto } from 'jsonplaceholder-api-client';
const response = await deletePhoto({ id: number });
/* Mock delete endpoint. Changes are not persisted (JSONPlaceholder behavior). */

📁 Resource Name: Posts

1. Get All Posts

import { getAllPosts } from 'jsonplaceholder-api-client';
const response = await getAllPosts();
/* Returns an array of post objects */

2. Get Post By ID

import { getPostById } from 'jsonplaceholder-api-client';
const response = await getPostById({ id: number });
/* If the post does not exist, post is returned as null */

3. Create Post

import { createNewPost } from 'jsonplaceholder-api-client';
const response = await createNewPost({
  userId: number,
  title: string,
  body: string,
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

4. Update Post

import { updatePost } from 'jsonplaceholder-api-client';
const response = await updatePost({
  id: number,
  data: { id: number, userId: number, title: string, body: string },
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

5. Partial Update Post

import { updatePostPartial } from "jsonplaceholder-api-client";
const response = await updatePostPartial({
  id: number,
  data: { userId?: number, title?: string, body?: string }
});
/* Need to give atleast 1 of the data fields. */
/* Changes are not persisted (JSONPlaceholder behavior). */

6. Delete Post

import { deletePost } from 'jsonplaceholder-api-client';
const response = await deletePost({ id: number });
/* Mock delete endpoint. Changes are not persisted (JSONPlaceholder behavior). */

📁 Resource Name: Todos

1. Get All Todos

import { getAllTodos } from 'jsonplaceholder-api-client';
const response = await getAllTodos();
/* Returns an array of todo objects */

2. Get Todo By ID

import { getTodoById } from 'jsonplaceholder-api-client';
const response = await getTodoById({ id: number });
/* If the todo does not exist, todo is returned as null */

3. Create Todo

import { createNewTodo } from 'jsonplaceholder-api-client';
const response = await createNewTodo({
  userId: number,
  title: string,
  completed: boolean,
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

4. Update Todo

import { updateTodo } from 'jsonplaceholder-api-client';
const response = await updateTodo({
  id: number,
  data: { id: number, userId: number, title: string, completed: boolean },
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

5. Partial Update Todo

import { updateTodoPartial } from "jsonplaceholder-api-client";
const response = await updateTodoPartial({
  id: number,
  data: { userId?: number, title?: string, completed?: boolean }
});
/* Need to give atleast 1 of the data fields. */
/* Changes are not persisted (JSONPlaceholder behavior). */

6. Delete Todo

import { deleteTodo } from 'jsonplaceholder-api-client';
const response = await deleteTodo({ id: number });
/* Mock delete endpoint. Changes are not persisted (JSONPlaceholder behavior). */

📁 Resource Name: Users

1. Get All Users

import { getAllUsers } from 'jsonplaceholder-api-client';
const response = await getAllUsers();
/* Returns an array of user objects */

2. Get User By ID

import { getUserById } from 'jsonplaceholder-api-client';
const response = await getUserById({ id: number });
/* If the user does not exist, user is returned as null */

3. Create User

import { createNewUser } from 'jsonplaceholder-api-client';
const response = await createNewUser({
  name: string,
  username: string,
  email: string,
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

4. Update User

import { updateUser } from "jsonplaceholder-api-client";
const response = await updateUser({
  id: number,
  data: {
    id: number
    name: string
    username: string
    email: string
    address: {
      street: string
      suite: string
      city: string
      zipcode: string
      geo: {
        lat: string
        lng: string
      }
    }
    phone: string
    website: string
    company: {
      name: string
      catchPhrase: string
      bs: string
    }
  }
});
/* All required fields. Changes not persisted (JSONPlaceholder behavior) */

5. Partial Update User

import { updateUserPartial } from "jsonplaceholder-api-client";
const response = await updateUserPartial({
  id: number,
  data: {
    name?: string
    username?: string
    email?: string
    address?: {
      street?: string
      suite?: string
      city?: string
      zipcode?: string
      geo?: {
        lat?: string
        lng?: string
      }
    }
    phone?: string
    website?: string
    company?: {
      name?: string
      catchPhrase?: string
      bs?: string
    }
  }
});
/* Need to give atleast 1 of the data fields. */
/* Changes are not persisted (JSONPlaceholder behavior). */

6. Delete User

import { deleteUser } from 'jsonplaceholder-api-client';
const response = await deleteUser({ id: number });
/* Mock delete endpoint. Changes are not persisted (JSONPlaceholder behavior). */

📗 Test Coverage

 PASS  src/todos/test/update-todo.test.ts
 PASS  src/users/test/update-user.test.ts
 PASS  src/users/test/get-all-users.test.ts
 PASS  src/users/test/get-user-by-id.test.ts
 PASS  src/users/test/update-user-partial.test.ts
 PASS  src/users/test/create-new-user.test.ts
 PASS  src/users/test/delete-user.test.ts
 PASS  src/albums/test/update-album-partial.test.ts
 PASS  src/photos/test/delete-photo.test.ts
 PASS  src/comments/test/create-new-comment.test.ts
 PASS  src/posts/test/update-post.test.ts
 PASS  src/albums/test/get-album-by-id.test.ts
 PASS  src/comments/test/update-comment-partial.test.ts
 PASS  src/posts/test/get-post-by-id.test.ts
 PASS  src/photos/test/update-photo.test.ts
 PASS  src/comments/test/get-comment-by-id.test.ts
 PASS  src/posts/test/update-post-partial.test.ts
 PASS  src/photos/test/update-photo-partial.test.ts
 PASS  src/photos/test/get-photo-by-id.test.ts
 PASS  src/comments/test/delete-comment.test.ts
 PASS  src/photos/test/get-all-photos.test.ts
 PASS  src/photos/test/create-new-photo.test.ts
 PASS  src/shared/test/index.test.ts
 PASS  src/albums/test/delete-album.test.ts
 PASS  src/comments/test/update-comment.test.ts
 PASS  src/albums/test/update-album.test.ts
 PASS  src/posts/test/get-all-posts.test.ts
 PASS  src/posts/test/create-new-post.test.ts
 PASS  src/posts/test/delete-post.test.ts
 PASS  src/comments/test/get-all-comments.test.ts
 PASS  src/albums/test/get-all-albums.test.ts
 PASS  src/albums/test/create-new-album.test.ts
 PASS  src/todos/test/create-new-todo.test.ts
 PASS  src/todos/test/update-todo-partial.test.ts
 PASS  src/todos/test/get-all-todos.test.ts
 PASS  src/todos/test/delete-todo.test.ts
 PASS  src/todos/test/get-todo-by-id.test.ts

If you would like to see a detailed report of the unit tests created and their respective file coverage, visit this test-coverage link.

📘 Contributing

Contributions, suggestions, and improvements are welcome.
Feel free to open issues or pull requests.

❤️ Support

Like this project? Support it with a github star, it would mean a lot to me! Cheers and Happy Coding.