Glossary

Endpoint

https://api.white.market/graphql/partner

Request

Request could be sent via an HTTP POST.

A standard GraphQL POST request should use the application/json content type, and include a JSON-encoded body of the following form:

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

operationName and variables are optional fields.

operationName is only required if multiple operations are present in the query.

Response

Regardless of the method by which the query and variables were sent, the response should be returned in the body of the request in JSON format. As mentioned in the spec, a query might result in some data and some errors, and those should be returned in a JSON object of the form:

{
  "data": { ... },
  "errors": [ ... ]
}

If there were no errors returned, the “errors” field should not be present on the response. If no data is returned, according to the GraphQL spec, the “data” field should only be included if no errors occurred during execution.

Errors

HTTP errors

GraphQL endpoint can return next HTTP codes

• 200 - body contain success response or GraphQL error;
• 400 - bad request JSON, bad GraphQL syntax, more than 1 mutation in 1 request;
• 401 - bad or expired JWT token in Authentication header;
• 429 - too many same mutations in one time, please send requests more slowly and separately;
• 503 - retry after some time described at Retry-After.

GraphQL errors

Error must contain:

• message - human readable error description;
• extension.category - mnemonic non-changeable error name.

Example:

{
  "errors": [
    {
      "message": "❗️ Oops! Item not found.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "market_item"
      ],
      "extensions": {
        "category": "market.product.not_found"
      }
    }
  ]
}

Query

A GraphQL operation can either be a read or a write operation.

A GraphQL query is used to read or fetch values. In either case, the operation is a simple string that a GraphQL server can parse and respond to with data in a specific format. The popular response format that is usually used for mobile and web applications is JSON.

Example:

#query with name myQuery
query myQuery{
    greeting
}

#query without any name
{
    greeting
}

З наведеного вище прикладу зрозуміло, що ключове слово запиту необов’язкове.

Запити GraphQL допомагають зменшити надмірне отримання даних. На відміну від Restful API, GraphQL дозволяє користувачеві обмежувати поля, які слід завантажувати із сервера. Це означає менші запити та менший трафік у мережі; що, у свою чергу, зменшує час відгуку.

Mutation

Mutation modify data in the data store and returns a value. It can be used to insert, update, or delete data. Mutations are defined as a part of the schema.

A GraphQL mutation is used to write or post values.

The syntax of a mutation is given below:

mutation{
   someEditOperation(dataField:"valueOfField"):returnType
}

Cursor Pagination

Cursor-based pagination allows for the ability to efficiently retrieve large datasets from a API by breaking them down into smaller pages. This method is particularly useful when working with large datasets where loading all the data at once would be impractical or slow.

Pros and cons

Benefits

One of the advantages of cursor-based pagination is its resilience to shifting rows. For example, if a record is deleted, the next record that would have followed is still displayed since the query is working off of the cursor rather than a specific offset.

Another benefit of cursor-based pagination is that it can work well with infinite scroll, a design trend that loads content as the user scrolls.

Drawbacks

One of the primary downsides of cursor-based pagination is that it’s impossible to directly address a specific page. For instance, if the requirement is to jump directly to page five, it’s not possible to do so since the pages themselves are not explicitly numbered.

Additionally, cursor-based pagination can be more complicated to implement than offset limit pagination. More thought needs to be put into the structure of the cursor and what criteria should be used to determine it.

Enum

An enum (short for “enumeration”) in GraphQL represents a finite set of predefined values.

It allows you to define a specific list of valid options for a field. Enums are useful when a field can only have a limited number of specific values.

For example, you might define an enum type for the possible statuses of a task, such as “COMPLETED,” “IN_PROGRESS,” or “CANCELLED.”

Enums provide a way to enforce a restricted set of values for a field, ensuring data consistency and preventing invalid inputs.

Type

A type in GraphQL defines a complex data structure with one or more fields. Types are used to describe the shape of data objects returned by the API. They can have multiple fields with different types, allowing you to represent and organize complex data relationships.

Types can be objects, interfaces, or unions. Object types represent a specific entity with its own set of properties and behaviors.

Interfaces define a common set of fields that multiple object types can implement.

Unions represent a type that can be one of several possible object types.

Summary

In summary, enums are used to define a specific set of allowed values for a field, while types are used to define the overall structure and relationships of data objects in GraphQL. Enums provide a way to restrict the possible values, ensuring data consistency and preventing errors, while types allow for flexible and complex data modeling.