8d2ff8a97e
Creates a new, comprehensive guide for the GraphQL API in `api/README.md`. This documentation details all available queries, mutations, and types, providing clear examples and explanations for developers. This addresses the most critical gap in the project's documentation, which was previously sparse and only covered a single query. The new documentation is structured for clarity and will serve as a vital resource for both internal and external developers.
5.5 KiB
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
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
work(id: ID!): Work
Retrieves a single work by its unique ID.
id: The ID of the work to retrieve.
Example:
query GetWork {
work(id: "1") {
id
name
language
content
stats {
likes
views
}
}
}
works(...)
Retrieves a list of works, with optional filters.
limit: The maximum number of works to return.offset: The number of works to skip for pagination.language: Filter works by language code (e.g., "en").authorId: Filter works by author ID.categoryId: Filter works by category ID.tagId: Filter works by tag ID.search: A string to search for in work titles and content.
Example:
query GetWorks {
works(limit: 10, language: "en") {
id
name
}
}
Translation
translation(id: ID!): Translation
Retrieves a single translation by its unique ID.
id: The ID of the translation.
translations(...)
Retrieves a list of translations for a given work.
workId: The ID of the parent work.language: Filter translations by language code.limit: The maximum number of translations to return.offset: The number of translations to skip.
Author
author(id: ID!): Author
Retrieves a single author by ID.
authors(...)
Retrieves a list of authors with optional filters.
User
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.
me: User
Retrieves the currently authenticated user.
Collection
collection(id: ID!): Collection
Retrieves a single collection by ID.
collections(...)
Retrieves a list of collections, optionally filtered by user.
Utility
trendingWorks(...)
Returns a list of works with the highest engagement.
timePeriod: "daily", "weekly", or "monthly". Defaults to "daily".limit: The number of works to return. Defaults to 10.
Mutations
This section details all available mutations for creating, updating, and deleting data.
Authentication Mutations
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.
Work Mutations
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 Mutations
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.
Like Mutations
createLike(input: LikeInput!): Like!
Adds a like to a work, translation, or comment. The input must contain exactly one of workId, translationId, or commentId.
Example:
mutation LikeWork {
createLike(input: { workId: "123" }) {
id
user {
id
}
}
}
deleteLike(id: ID!): Boolean!
Removes a previously added like.
Comment Mutations
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.
Core Types
Work: Represents a literary work.Translation: Represents a translation of aWork.Author: Represents the creator of aWork.User: Represents a platform user.Comment: Represents a comment on aWorkorTranslation.Like: Represents a like on aWork,Translation, orComment.Collection: Represents a user-curated collection of works.WorkStats/TranslationStats: Represents analytics data for content.