logicspark / vitepress-theme-api Goto Github PK

---
layout: pon
aside: left
---

<script setup>import {DividePage} from 'vitepress-theme-api';</script>
<style>@import './node_modules/vitepress-theme-api/dist/style.css';</style>

# GraphQL API Guide

[GraphQL](https://graphql.org/) is a query language for APIs that offers an efficient and versatile alternative to REST APIs.


## Benefits of Using GraphQL Over REST:

1. **Single Endpoint:** GraphQL employs a single endpoint for all queries and mutations, contrasting with REST which necessitates multiple endpoints.

2. **Streamlined Data Retrieval:** With GraphQL, there's no need for intermediary datastores or additional layers when collating related data.

3. **Precise Data Retrieval:** Clients dictate the exact data they need, ensuring swift and succinct responses.

4. **HTTP-Based:** GraphQL, despite its unique query language, operates via standard HTTP, meaning any client capable of HTTP requests can interface with a GraphQL server. No GraphQL specific libraries are needed.

<DividePage>
<template #left>

## Authentication

Use the `Authorization` HTTP header with your personal access token.

</template>
<template #right>

**Header:**

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

</template>
</DividePage>

<DividePage>
<template #left>

### Obtaining a Personal Access Token

[PLACEHOLDER: Instructions or link for token.]

</template>
<template #right>

</template>
</DividePage>

<DividePage>
<template #left>

## Filters

Filters empower you to fine-tune your GraphQL queries, allowing you to retrieve data based on specific conditions. This guide will showcase the usage of `DeviceFilter`, `TagFilter`, and `StringConditional` filters when querying devices in the provided schema.

### DeviceFilter

The `DeviceFilter` is specifically crafted for querying devices based on specific attributes such as type, label, status, and tags.

</template>
<template #right>

#### Filtering by Connection Status

To filter devices by their connection status, use the `status` attribute of `DeviceFilter` and choose a value from the `ConnectionStatus` enum.

graphql [GraphQL]
{
  myDevices(filter: { status: "GOOD" }) {
	content {
	  id
	  label
	  type
	}
  }
}

This query retrieves devices with a connection status of "GOOD".

#### Filtering by Label

To query devices based on their label, employ the `label` attribute in conjunction with `StringConditional`.

graphql [GraphQL]
{
  myDevices(filter: { label: { eq: "MyVehicle" } }) {
	content {
	  id
	  label
	  type
	}
  }
}

In this example, devices labeled "MyVehicle" are fetched.

</template>
</DividePage>

Show All