About the GraphQL API

Welcome to the GraphQL Fundamentals section, where we'll cover essential concepts and best practices for utilizing our GraphQL API effectively.

Table of Contents

1. Introduction to GraphQL
2. API Exploration
3. Error Handling
4. Query Structure
5. Performance Considerations
6. Pagination
7. Rate Limiting

Introduction to GraphQL

GraphQL is a powerful query language for APIs that allows clients to request only the data they need. Understanding its core principles will help you make the most of our API.

• Declarative Data Fetching: Specify the shape and structure of the data you need, and GraphQL will return exactly that.

• Single Request, Multiple Resources: Unlike traditional REST APIs, GraphQL enables you to retrieve multiple resources in a single request, reducing the number of API calls.

API Exploration

To use our GraphQL API, you need to be logged in as a user. Here are some key details:

• Explore the Documentation: Click here to explore our documentation. It is directly linked to our Nitro environment, allowing you to explore and view possibilities, hierarchy using the Reference schema.

• Built on Hot Chocolate: Our GraphQL API is built on the open-source GraphQL server Hot Chocolate. For detailed information on features such as filtering or sorting your search, we recommend reading Hot Chocolate's documentation.

• Interface with Nitro: We use the Hot Chocolate interface to display field documentation and provide a pleasant experience with the API. Refer to Nitro for more information.

• Current Version: We are currently using Hot Chocolate v13.9.0.

If you need help getting started with the Momentum Fastighet GraphQL API, refer to the Get started guide. Additionally, find assistance in designing your queries in the Query Examples guide.

To clarify, the interface provided is not used for retrieving data but rather for the design of queries and validation of data.

Error Handling

When working with GraphQL, it's crucial to implement proper error handling to gracefully manage potential issues. Every GraphQL response includes an errors field that provides details about any encountered errors.

Here's a list of error codes that can occur in our GraphQL API.

Ensure your client applications are equipped to handle these errors and extract relevant information from the errors array.

Example:

{
  "errors": [
    {
      "message": "The current user is not authorized to access this resource.",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ],
      "path": [
        "nodes"
      ],
      "extensions": {
        "code": "AUTH_NOT_AUTHORIZED"
      }
    }
  ],
  "data": null
}

Query Structure

Understanding the structure of GraphQL queries is essential for effective data retrieval. Take advantage of features like nested queries, aliases, and fragments to optimize your requests. Ensure that you are only requesting the data you need to minimize the payload size.

{
  customer(id: "123") {
    name
    contracts {
      id
      number
    }
  }
}

Performance Considerations

As with any API, consider the performance implications of your GraphQL queries. Avoid over-fetching data by requesting only the fields necessary for your application. Additionally, be mindful of the potential for N+1 query issues when fetching related data.

Pagination

When dealing with large datasets, pagination becomes crucial to efficiently retrieve and display data. Our GraphQL API supports pagination through the use of first and after parameters. Here's an example:

{
  customers(first: 10, after: "cursor") {
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

In this example, first specifies the number of items per page, and after indicates the cursor from which to start fetching data.

Read more on this in our Guides section.

Rate Limiting

To ensure fair usage of our GraphQL API and prevent abuse, rate limiting is enforced. Exceeding the allowed rate limit will result in a temporary suspension of API access.

Please refer to our Rate Limiting section for detailed information on how our rate limit is calculated.

Keep these fundamentals in mind as you interact with our GraphQL API to build efficient and scalable applications.