PlayPI

PlayPI (pronounced as Play-P-I, similar to API) is an open-source, simple, and local API playground that allows software engineers to test and experiment with various types of APIs. It is designed for hands-on learning and testing without requiring an internet connection or complex setup.

With PlayPI, you can practice API testing across multiple technologies and protocols, including RESTful, gRPC, GraphQL, and WebSocket (and more to come). You can also use this playground if you are conducting a hands-on API testing workshop or bootcamp.

Why PlayPI?

PlayPI stands out as a versatile, multi-protocol API playground:

Quick Start Using CLI

Download the Binary

  1. Go to the Releases page of this repository.
  2. Download the binary for your platform (only macOS & Linux supported currently).
  3. Make the binary executable (if required): chmod +x playpi

Run the Playground

Use the following command to start the desired service: ./playpi start [api-type]

Replace [api-type] with one of the following:

Example:

./playpi start restful-inventory-manager

Docker Installation and Usage

Pull the Docker Image

docker pull abhivaikar/playpi:latest

Run the Playground

Run a specific API service: docker run -p <port>:<port> abhivaikar/playpi start [api-type]

Replace <port> and [api-type] as needed.

Example:

Accessing a service once started

Which client you want to use to access the service on the playground is entirely upto you. But here are some suggestions.

APIs and Use Cases

RESTful API - Inventory Management

CRUD operations to manage an inventory of items. Example operations include adding, updating, deleting, and retrieving items.

Create item

HTTP Method: POST URL: /items Payload:

{
"name": "Laptop",
"description": "A high-performance laptop",
"price": 1500.99,
"quantity": 10
}

Update item

HTTP Method: PUT URL: items/{id} Payload:

{
"name": "Laptop",
"description": "A high-performance laptop",
"price": 1500.99,
"quantity": 1
}

Delete item

HTTP Method: DELETE URL: items/{id} Payload: No payload

Get all items

HTTP Method: GET URL: /items

Update item - specific field

HTTP Method: PATCH URL: items/{id} Payload:

{
"quantity" : 1
}

RESTful API - Task Management

Manage tasks with fields such as title, description, due date, and status. Tasks can be marked as overdue based on their due date.

Create a new task

HTTP Method: POST URL: /tasks Payload:

{
"title": "Write documentation",
"description": "Document all APIs for the PlayPI project",
"due_date": "2025-01-15",
"priority": "high"
}

Update a task

HTTP Method: PUT URL: /tasks/1 Payload:

{
"title": "Finalize documentation",
"description": "Update and finalize all API docs",
"due_date": "2025-01-20",
"priority": "medium",
"status": "in progress"
}

Mark task as complete

HTTP Method: PUT URL: /tasks/1/complete Payload: N/A

Get all tasks

HTTP Method: GET URL: /tasks

Get a task

HTTP Method: GET URL: /tasks/{id}

Delete a task

HTTP Method: DELETE URL: /tasks/{id}

gRPC API - Inventory Management

AddItem

Payload

{
"description": "reprehenderit ex et anim",
"name": "Ut mollit",
"price": 10,
"quantity": 12
}

GetItem

Payload

{
"id": 1
}

ListItems

No payload

UpdateItem

Payload

{
"description": "dolor et nostrud reprehenderit",
"id": 1,
"name": "ex ut velit fugiat eiusmod",
"price": 6668482.157076433,
"quantity": 1800787081
}

DeleteItem

Payload

{
"id": 1
}

gRPC API - User Registration and Sign-In

RegisterUser

Payload:

{
"user": {
"address": "ut",
"email": "consectetur@gmail.com",
"full_name": "test",
"password": "test",
"phone": "2323431",
"username": "testuser"
 }
}

SignIn

Payload:

{
"password": "test",
"username": "testuser"
}

GetProfile

Payload:

{
"token": "token_from_signin_response"
}

UpdateProfile

Payload:

{
"token": "token_from_signin",
"user": {
"address": "sint",
"email": "xyz@gmail.com",
"full_name": "cillum sed",
"password": "awdad",
"phone": "43141",
"username": "updated_username"
 }
}

DeleteAccount

Payload:

{
"token": "token_from_signin"
}

GraphQL API - Inventory management

Query and mutate inventory data with a flexible schema. Example: Fetch a list of items, retrieve specific details, or update inventory.

Get all items

{
  items {
    id
    name
    description
    price
    quantity
  }
}

Get item by item id

{
item(id: 1) {
name
description
quantity
}
}

Add item

mutation {
addItem(name: "Headphones", description: "Noise-canceling headphones", price: 299.99, quantity: 10) {
id
name
description
 }
}

Update item

mutation {
updateItem(id: 1, name: "Updated Laptop", quantity: 20) {
id
name
description
price
quantity
 }
}

Delete item

mutation {
deleteItem(id: 2)
}

WebSocket API - Inventory Management

Real-time updates to all connected clients when inventory changes occur.

Add item broadcast

{
  "type": "add_item",
  "payload": {
    "name": "Laptop",
    "description": "High-performance laptop",
    "price": 1500.99,
    "quantity": 10
  }
}

Get all items

{
  "type": "get_all_items"
}

Update an item

{
  "type": "update_item",
  "payload": {
    "id": 1,
    "quantity": 20
  }
}

Delete an item

{
  "type": "delete_item",
  "payload": {
    "id": 1
  }
}

WebSocket API - Live Chat

Multi-user chat functionality with join/leave notifications and private messaging.

Join a chat

Send below message to indicate you have joined the chat after connecting to the websocket server. Other clients who have joined will get a broadcast that you have joined the chat.

"john_doe"

Broadcast a message to all chat users

{
    "type": "chat",
    "username": "john_doe",
    "message": "Hello, everyone!"
}

Send a private message to a specific user

{
    "type": "private",
    "username": "john_doe",
    "message": "Hi Jane!",
    "to": "jane_doe"
}

Leave chat

You just need to disconnect from the websocket connection and all other clients connected to the websocket will get a message that you have left.

Contributing to PlayPI

We welcome contributions to make PlayPI even better! Whether it’s fixing a bug, suggesting a new feature, or improving the documentation, your input is valuable.

The most important contributions needed will be to add new and real-world use cases (beyond inventory, task manager, chat etc) and/or protocols (beyond restful, gRPC, websocket etc).

How to Contribute

  1. Fork the repository
  2. Clone your fork locally
  3. Create a new branch
  4. Make your changes
    • Add new features, fix bugs, refactor existing code, add tests or improve documentation.
  5. Test your changes locally to ensure they work as expected.
    • Currently the project does not have automated tests for the services. We will be adding them soon and create an automated build and test Github actions pipeline.
  6. Commit and push
  7. Submit a pull request
    • Go to your forked repository on GitHub.
    • Click the “Compare & pull request” button.
    • Describe your changes and submit the pull request.

Reporting Issues and Feedback

We value your feedback to improve PlayPI. If you encounter any issues or have suggestions, here’s how you can raise them:

  1. Search for existing issues:

    • Check the Issues tab on GitHub to see if your issue has already been reported.
  2. Create a new issue:
    • If your issue or feedback is new, click on the “New Issue” button in the Issues tab.
    • Provide a clear and detailed description of the issue or feedback:
      • What were you trying to do?
      • What happened instead?
      • Steps to reproduce the issue (if applicable).
      • Any relevant logs or screenshots.
  3. Feature requests:
    • Label your issue as a “Feature Request” and provide details about the functionality you’d like to see.