ripplit/ripplit_service_desc

Ripplit Service Documentation

Overview

The Ripplit Service is a RESTful API built using Ballerina that manages users and their associated posts. It provides a flexible way to handle CRUD (Create, Read, Update, Delete) operations for both users and posts, allowing seamless interaction with the underlying system. This service is designed to serve as the backend for social or blog-like platforms where users can register, create posts, and manage their profiles.

Key Features:

• User Management:
  • Create, retrieve, and delete users.
  • Validate user inputs like name length during user creation.
• Post Management:
  • Retrieve posts for all users or a specific user.
  • Create posts for specific users with metadata such as tags, category, and creation timestamp.
• Error Handling:
  • Provides detailed error responses for scenarios such as user not found, forbidden post creation, and validation failures.

This service supports a typical REST API interaction style, with HTTP methods like GET, POST, and DELETE mapped to specific resource paths for handling requests. Below is a detailed breakdown of the API endpoints and data types used in the service.

Resources

GET /users

Retrieves all users from the system. This endpoint allows clients to fetch the list of all registered users.

Response

• 200 OK: Returns an array of User objects containing the details of all users.
• 500 Internal Server Error: If an error occurs while fetching the users, returns an error object.

GET /users/{id}

Fetches the details of a specific user by their unique ID. This endpoint allows clients to retrieve individual user profiles based on the provided id.

Path Parameters

• id (int): The ID of the user to retrieve.

Response

• 200 OK: Returns a User object containing the user’s details.
• 404 Not Found: If the user with the specified ID is not found, returns a UserNotFound object.
• 500 Internal Server Error: Returns an error if something goes wrong while retrieving the user.

POST /users

Creates a new user. This endpoint accepts user details in the request body and registers a new user in the system.

Request Body

• newUser (NewUser): A JSON object containing the user’s name, birth date, and mobile number.

Response

• 201 Created: Returns http:Created indicating the user was successfully created.
• 400 Bad Request: If the input validation fails (e.g., name too short), returns an appropriate error.
• 500 Internal Server Error: If any server-side error occurs during user creation, returns an error.

DELETE /users/{id}

Deletes an existing user by their unique ID. This endpoint permanently removes the user from the system.

Path Parameters

• id (int): The ID of the user to delete.

Response

• 204 No Content: Indicates the user was successfully deleted.
• 404 Not Found: If the user with the specified ID is not found.
• 500 Internal Server Error: Returns an error if something goes wrong during the deletion process.

GET /posts

Retrieves all posts made by all users. This is a general endpoint for fetching all user-generated content.

Response

• 200 OK: Returns an array of PostWithMeta objects, each containing details and metadata about the posts.
• 500 Internal Server Error: Returns an error if the posts cannot be fetched.

GET /users/{id}/posts

Retrieves all posts for a specific user. This allows clients to fetch posts authored by a given user.

Path Parameters

• id (int): The ID of the user whose posts are to be retrieved.

Response

• 200 OK: Returns an array of PostWithMeta objects containing the posts created by the user.
• 404 Not Found: If the user with the specified ID is not found, returns a UserNotFound object.
• 500 Internal Server Error: Returns an error if something goes wrong while retrieving the posts.

POST /users/{id}/posts

Creates a new post for a specific user. This allows users to post new content under their profile.

Path Parameters

• id (int): The ID of the user for whom the post is created.

Request Body

• newPost (NewPost): A JSON object containing the post's description, tags, and category.

Response

• 201 Created: Returns http:Created indicating the post was successfully created.
• 403 Forbidden: If the user is not allowed to create a post, returns a PostForbidden object.
• 404 Not Found: If the user with the specified ID is not found, returns a UserNotFound object.
• 500 Internal Server Error: Returns an error if something goes wrong while creating the post.

Data Types

User

A record type representing a user.

NewUser

A record type representing a new user to be created.

UserNotFound

A record type representing a user not found error.

Post

A record type representing a post.

PostWithMeta

A record type representing a post with metadata.

meta

• tags: An array of strings representing post tags.
• category: The category of the post.
• createdTimeStamp: Timestamp of post creation.

NewPost

A record type representing a new post to be created.

PostForbidden

A record type representing a forbidden action for creating a post.

ErrorDetails

A record type for representing error details.

This document provides a comprehensive overview of the Ripplit Service, including API endpoints, data types, and expected responses, making it easier for developers to interact with the service.