Return objects

[EduardoWDias]

Proposal for discussion of what our return objects could be, following the best language practices.

This discussion item is related to #47.

[EduardoWDias]

https://think-it.io/insights/GraphQL-best-practice
I found this to be a good resource on GraphQL best practices, here is a few key points:

Designing a GraphQL schema with flexibility and scalability in mind involves several key principles that ensure the schema can grow and adapt to changing requirements while maintaining performance and usability.

• Unified Schema: A GraphQL schema defines a collection of types and their relationships in a unified manner. This allows client developers to request specific subsets of data with optimized queries, enhancing flexibility.

• Implementation-Agnostic: The schema is not responsible for defining data sources or storage methods, making it adaptable to various backend implementations without requiring changes to the schema itself.

• Field Nullability: By default, fields can return null, but non-nullable fields can be specified using an exclamation mark (!). This provides control over data integrity and error handling, contributing to robust and scalable schema design.

• Query-Driven Design: The schema should be designed based on client needs rather than backend data structures. This approach ensures that the schema evolves with client requirements, supporting flexibility and scalability.

• Version Control and Change Management: Maintaining the schema in version control allows tracking of changes over time. Most additive changes are backward compatible, but careful management of breaking changes is essential for scalability.

• Use of Descriptions: Incorporating Markdown-enabled documentation strings (descriptions) in the schema helps developers understand and use the schema effectively, promoting a flexible development environment.

• Naming Conventions: Consistent naming conventions, such as camelCase for fields and PascalCase for types, ensure clarity and ease of use across different client implementations, aiding in scalability.

[DanielSOliveiram]

• A recommended best practice is to avoid returning primitive types (such as int or String) or domain entities (like Task) directly in your GraphQL responses. Instead, consider designing response types that encapsulate the result along with relevant metadata, such as status indicators or error messages. This approach promotes consistency, improves client-side error handling, and aligns with the GraphQL specification, which encourages structured and predictable responses. https://graphql.org/learn/response/

[EduardoWDias]

https://graphql.org/learn/response/

Here are also a few key points about GraphQL response formats:

• The GraphQL specification allows three top-level keys in a response: data, errors, and extensions

• At least one of data or errors will be present on the response (when it contains both it is a “partial response”)

• The data key contains the result of the executed operation

• Information about raised errors is included in the errors key of the response

• Request errors (such as syntax or validation errors) are raised before execution begins so data won’t be included in the response

• When a field error occurs during execution, there will be a description of the issue in the errors key and there may be partial data included with the data key

• GraphQL implementations may include additional arbitrary information about the response in the extensions key

[BomDju]

Best Practices for Structuring GraphQL Request Responses:

Always return objects, not simple values
Even if the endpoint returns something simple (like a boolean), it's recommended to return an object with context to make future extensions easier.

❌ Avoid this:

mutation{
  deletUser(id:"123") //retorna apemas true/false 
}

✅ Prefer this:

mutation{
  deletUser(id:"123"){
    success
    message
    deletUserId
  }
}

📃 Pagination Pattern (Relay-style ou Offset-based)

For large lists, use a consistent pagination pattern

• Relay-style

type PageInfo{
 hasNextPage:Boolean!
 endCursor:String
}

type UserConnection{
 edges:[UserEdge!]!
 pageInfo: PageInfo!
}

type UserEdge{
 cursor:String!
 node:User!
}

• Offset-based

type UserPage{
 totalCount: Int!
 users: [User!]
 offset: Int!
 limit: Int!
}

🪲Tratamento consisitente de erros

• GraphQL separates data and errors in the JSON response.
• However, it's a good practice to create types that represent errors in a controlled way within the data, especially for mutations.

type Mutationresponse{
  success> Bolean!
  message: String
  erros: [FieldError]
 }
 
 type FieldError{
   field: String!
   message:String!
}

🗣️Nameing convention (camelCase)

• Use camelCase for field names
• Avoid obscure abbreviations and follow consistent naming conventions

🌎Centralização de objetos de resposta padrão

It's a good practice to define types like MutationResponse, ErrorPlayLoad, PaginationInfo etc. That can be reused across multiple parts of the schema.