json-placeholder-client-sdk

A fully-typed TypeScript SDK for the JSONPlaceholder REST API — the free fake API for testing and prototyping.

Installation

npm install json-placeholder-client-sdk

Quick Start

import { JSONPlaceholderSDK } from 'json-placeholder-client-sdk'

const sdk = new JSONPlaceholderSDK()

const todo = await sdk.todos.getById(1)
console.log(todo)
// { userId: 1, id: 1, title: 'delectus aut autem', completed: false }

Resources

The SDK exposes six namespaced resource clients:

| Namespace | Records | Description | |-----------|---------|-------------| | sdk.posts | 100 | Blog posts | | sdk.comments | 500 | Post comments | | sdk.albums | 100 | Photo albums | | sdk.photos | 6000 | Album photos | | sdk.todos | 200 | Todo items | | sdk.users | 10 | Users |

API Reference

Every resource exposes the same set of CRUD methods. Some resources also expose nested relationship methods.

Common Methods (all resources)

// Get all items
await sdk.posts.getAll()         // IPost[]

// Get a single item by id
await sdk.posts.getById(1)       // IPost

// Create a new item (id is auto-assigned)
await sdk.posts.create({
    userId: 1,
    title: 'My post',
    body: 'Hello world'
})                               // IPost

// Full replace
await sdk.posts.update(1, {
    userId: 1,
    title: 'Updated title',
    body: 'Updated body'
})                               // IPost

// Partial update
await sdk.posts.patch(1, { title: 'Just the title changed' })  // IPost

// Delete
await sdk.posts.delete(1)        // void

Note: JSONPlaceholder is a mock API. Write operations (create / update / patch / delete) return realistic responses but do not persist data.

Posts

const sdk = new JSONPlaceholderSDK()

// All CRUD methods (see above)
const posts = await sdk.posts.getAll()
const post  = await sdk.posts.getById(1)

// Get comments on a specific post
const comments = await sdk.posts.getComments(1)  // IComment[]

Comments

const comments = await sdk.comments.getAll()
const comment  = await sdk.comments.getById(1)

// Filter comments by post id
const postComments = await sdk.comments.getByPost(1)  // IComment[]

Albums

const albums = await sdk.albums.getAll()
const album  = await sdk.albums.getById(1)

// Get photos inside an album
const photos = await sdk.albums.getPhotos(1)  // IPhoto[]

Photos

const photos = await sdk.photos.getAll()
const photo  = await sdk.photos.getById(1)
// { albumId: 1, id: 1, title: '...', url: '...', thumbnailUrl: '...' }

Todos

const todos = await sdk.todos.getAll()
const todo  = await sdk.todos.getById(1)

// Mark a todo complete
const updated = await sdk.todos.patch(1, { completed: true })

Users

const users = await sdk.users.getAll()
const user  = await sdk.users.getById(1)

// Nested relationships
const userPosts  = await sdk.users.getPosts(1)   // IPost[]
const userAlbums = await sdk.users.getAlbums(1)  // IAlbum[]
const userTodos  = await sdk.users.getTodos(1)   // ITodo[]

TypeScript Types

All types are exported from the package:

import type {
    ITodo,
    IPost,
    IComment,
    IAlbum,
    IPhoto,
    IUser
} from 'json-placeholder-client-sdk'

Full Example

import { JSONPlaceholderSDK } from 'json-placeholder-client-sdk'
import type { IPost, IComment } from 'json-placeholder-client-sdk'

const sdk = new JSONPlaceholderSDK()

async function main() {
    // Fetch a user and all their posts
    const user = await sdk.users.getById(1)
    console.log(`User: ${user.name} (${user.email})`)

    const posts = await sdk.users.getPosts(1)
    console.log(`Posts by ${user.name}:`, posts.length)

    // Fetch comments on the first post
    const comments: IComment[] = await sdk.posts.getComments(posts[0].id)
    console.log(`Comments on "${posts[0].title}":`, comments.length)

    // Create a new todo
    const newTodo = await sdk.todos.create({
        userId: 1,
        title: 'Buy groceries',
        completed: false
    })
    console.log('Created todo:', newTodo)

    // Mark it complete
    const done = await sdk.todos.patch(newTodo.id, { completed: true })
    console.log('Completed:', done.completed)
}

main()

License

ISC