tercul-backend/api

Tercul API Documentation

This document provides comprehensive documentation for the Tercul GraphQL API. It is designed to give developers all the information they need to interact with the platform's data and services.

Table of Contents

• Introduction
• Authentication
• Queries
• Mutations
• Core Types
• Input Types
• Enums
• Scalars

Introduction

The Tercul API is a GraphQL-based service that exposes the full range of the platform's literary and social data. It allows for querying works, translations, authors, and user data, as well as performing actions such as creating content, liking, and commenting.

Authentication

Most mutations and some queries require authentication. To authenticate, you must first use the login mutation to receive a JWT. This token must then be included in the Authorization header of subsequent requests as a Bearer token.

Example Header: Authorization: Bearer <your_jwt_token>

---

Queries

This section details all available queries.

Work Queries

• work(id: ID!): Work: Retrieves a single work by its unique ID.
• works(limit: Int, offset: Int, language: String, authorId: ID, categoryId: ID, tagId: ID, search: String): [Work!]!: Retrieves a list of works with optional filters and pagination.

Translation Queries

• translation(id: ID!): Translation: Retrieves a single translation by its unique ID.
• translations(workId: ID!, language: String, limit: Int, offset: Int): [Translation!]!: Retrieves a list of translations for a given work.

Book Queries

• book(id: ID!): Book: Retrieves a single book by ID.
• books(limit: Int, offset: Int): [Book!]!: Retrieves a list of all books.

Author Queries

• author(id: ID!): Author: Retrieves a single author by ID.
• authors(limit: Int, offset: Int, search: String, countryId: ID): [Author!]!: Retrieves a list of authors with optional filters.

User Queries

• user(id: ID!): User: Retrieves a single user by ID.
• userByEmail(email: String!): User: Retrieves a single user by email address.
• userByUsername(username: String!): User: Retrieves a single user by username.
• users(limit: Int, offset: Int, role: UserRole): [User!]!: Retrieves a list of users, with optional role filter.
• me: User: Retrieves the currently authenticated user.
• userProfile(userId: ID!): UserProfile: Retrieves the profile for a given user.

Collection Queries

• collection(id: ID!): Collection: Retrieves a single collection by ID.
• collections(userId: ID, limit: Int, offset: Int): [Collection!]!: Retrieves a list of collections, optionally filtered by user.

Tag & Category Queries

• tag(id: ID!): Tag: Retrieves a single tag by ID.
• tags(limit: Int, offset: Int): [Tag!]!: Retrieves a list of all tags.
• category(id: ID!): Category: Retrieves a single category by ID.
• categories(limit: Int, offset: Int): [Category!]!: Retrieves a list of all categories.

Comment Queries

• comment(id: ID!): Comment: Retrieves a single comment by ID.
• comments(workId: ID, translationId: ID, userId: ID, limit: Int, offset: Int): [Comment!]!: Retrieves a list of comments with optional filters.

Utility Queries

• search(query: String!, limit: Int, offset: Int, filters: SearchFilters): SearchResults!: Performs a sitewide search across works, translations, and authors.
• trendingWorks(timePeriod: String, limit: Int): [Work!]!: Returns a list of works with the highest engagement. timePeriod can be "daily", "weekly", or "monthly".

---

Mutations

This section details all available mutations for creating, updating, and deleting data.

Authentication

• register(input: RegisterInput!): AuthPayload!: Creates a new user account.
• login(input: LoginInput!): AuthPayload!: Authenticates a user and returns a JWT.
• logout: Boolean!: Logs out the currently authenticated user.
• refreshToken: AuthPayload!: Issues a new JWT for an active session.
• forgotPassword(email: String!): Boolean!: Initiates the password reset process for a user.
• resetPassword(token: String!, newPassword: String!): Boolean!: Resets a user's password using a valid token.
• verifyEmail(token: String!): Boolean!: Verifies a user's email address using a token.
• resendVerificationEmail(email: String!): Boolean!: Resends the email verification link.

User & Profile

• updateUser(id: ID!, input: UserInput!): User!: Updates a user's details (Admin).
• deleteUser(id: ID!): Boolean!: Deletes a user account (Admin).
• updateProfile(input: UserInput!): User!: Allows a user to update their own profile information.
• changePassword(currentPassword: String!, newPassword: String!): Boolean!: Allows an authenticated user to change their password.

Work

• createWork(input: WorkInput!): Work!: Creates a new work.
• updateWork(id: ID!, input: WorkInput!): Work!: Updates an existing work.
• deleteWork(id: ID!): Boolean!: Deletes a work.

Translation

• createTranslation(input: TranslationInput!): Translation!: Creates a new translation for a work.
• updateTranslation(id: ID!, input: TranslationInput!): Translation!: Updates an existing translation.
• deleteTranslation(id: ID!): Boolean!: Deletes a translation.

Book

• createBook(input: BookInput!): Book!: Creates a new book.
• updateBook(id: ID!, input: BookInput!): Book!: Updates an existing book.
• deleteBook(id: ID!): Boolean!: Deletes a book.

Author

• createAuthor(input: AuthorInput!): Author!: Creates a new author.
• updateAuthor(id: ID!, input: AuthorInput!): Author!: Updates an existing author.
• deleteAuthor(id: ID!): Boolean!: Deletes an author.

Collection

• createCollection(input: CollectionInput!): Collection!: Creates a new collection.
• updateCollection(id: ID!, input: CollectionInput!): Collection!: Updates an existing collection.
• deleteCollection(id: ID!): Boolean!: Deletes a collection.
• addWorkToCollection(collectionId: ID!, workId: ID!): Collection!: Adds a work to a collection.
• removeWorkFromCollection(collectionId: ID!, workId: ID!): Collection!: Removes a work from a collection.

Comment

• createComment(input: CommentInput!): Comment!: Adds a comment to a work or translation.
• updateComment(id: ID!, input: CommentInput!): Comment!: Updates an existing comment.
• deleteComment(id: ID!): Boolean!: Deletes a comment.

Like

• createLike(input: LikeInput!): Like!: Adds a like to a work, translation, or comment.
• deleteLike(id: ID!): Boolean!: Removes a previously added like.

Bookmark

• createBookmark(input: BookmarkInput!): Bookmark!: Creates a bookmark for a work.
• deleteBookmark(id: ID!): Boolean!: Deletes a bookmark.

Contribution

• createContribution(input: ContributionInput!): Contribution!: Creates a new contribution.
• updateContribution(id: ID!, input: ContributionInput!): Contribution!: Updates a contribution.
• deleteContribution(id: ID!): Boolean!: Deletes a contribution.
• reviewContribution(id: ID!, status: ContributionStatus!, feedback: String): Contribution!: Reviews a contribution, setting its status and providing feedback.

---

Core Types

This section describes the main data structures in the API.

• Work: Represents a literary work. Contains fields for content, metadata, and associations to authors, translations, etc.
• Translation: Represents a translation of a Work.
• Author: Represents the creator of a Work.
• User: Represents a platform user.
• UserProfile: Contains extended profile information for a User.
• Book: Represents a book, which can contain multiple works.
• Collection: Represents a user-curated collection of works.
• Tag: A keyword or label associated with a Work.
• Category: A classification for a Work.
• Comment: A user-submitted comment on a Work or Translation.
• Like: Represents a "like" action from a user on a Work, Translation, or Comment.
• Bookmark: A user's personal bookmark for a Work.
• Contribution: Represents a user's submission of a new work or translation.
• ReadabilityScore: Flesch-Kincaid or similar readability score for a Work.
• WritingStyle: Analysis of the writing style of a Work.
• Emotion: Emotional analysis result for a piece of content.
• TopicCluster: A cluster of related topics for a Work.
• Mood: The detected mood of a Work.
• Concept: A key concept extracted from a Work.
• Word: A specific word linked to a Concept.
• LinguisticLayer: Detailed linguistic analysis of a Work.
• WorkStats / TranslationStats / etc.: Analytics data (views, likes, etc.) for various entities.
• TextMetadata: General metadata from text analysis.
• PoeticAnalysis: Specific analysis of poetic structure.
• Copyright / CopyrightClaim: Information related to copyright ownership and claims.
• Country / City / Place / Address: Location-related data for users and authors.
• Source: The original source of a work or translation.
• Edge: A generic graph edge for representing relationships between entities.
• SearchResults: A container for results from the search query.
• AuthPayload: A container for the authentication token and user object returned upon login/registration.

---

Input Types

This section describes the input objects used in mutations.

• LoginInput: Contains email and password for the login mutation.
• RegisterInput: Contains username, email, password, firstName, and lastName for the register mutation.
• WorkInput: Used for creating/updating a Work.
• TranslationInput: Used for creating/updating a Translation.
• AuthorInput: Used for creating/updating an Author.
• BookInput: Used for creating/updating a Book.
• UserInput: Used for updating user data.
• CollectionInput: Used for creating/updating a Collection.
• CommentInput: Used for creating/updating a Comment.
• LikeInput: Specifies the entity to be liked (workId, translationId, or commentId).
• BookmarkInput: Used for creating a Bookmark.
• ContributionInput: Used for creating/updating a Contribution.
• SearchFilters: A set of optional filters for the search query.

---

Enums

• UserRole: Defines the possible roles for a user (READER, CONTRIBUTOR, REVIEWER, EDITOR, ADMIN).
• ContributionStatus: Defines the lifecycle status of a contribution (DRAFT, SUBMITTED, UNDER_REVIEW, APPROVED, REJECTED).

---

Scalars

• JSON: A standard JSON object. Used for flexible data fields like user preferences.