UnionSkill API Docs

1. 快速开始

1. 获取 API Key
   访问 hub.unionskillai.com，点击「获取密钥」生成专属 API Key。
2. 发送第一个请求

   curl -X POST https://api.unionskillai.com/ \
     -H 'Content-Type: application/json' \
     -H 'X-API-Key: YOUR_API_KEY' \
     -d '{"query": "{ order(id: \"o1\") { id total user { name } } }"}'

3. 获取响应

   {
     "data": {
       "order": {
         "id": "o1",
         "total": 88,
         "user": { "name": "Alice Zhang" }
       }
     }
   }

2. 认证方式

所有 API 请求必须携带 API Key，通过 HTTP Header 传递：

3. GraphQL API

端点

基于 Apollo Federation 2 构建的联邦化 GraphQL 超图，包含以下子图：

子图	实体	说明
products	Product	产品目录、价格、库存
users	User	用户信息、认证
orders	Order, OrderItem	订单、订单明细

示例查询

查询订单详情（跨子图联邦查询）

query {
  order(id: "o1") {
    id
    total
    user {
      name
      email
    }
    items {
      productId
      quantity
      product {
        name
        price
      }
    }
  }
}

查询产品列表

query {
  products {
    id
    name
    price
    stock
  }
}

REST Connectors

GraphQL 超图同时集成了外部 REST API（通过 Apollo Connectors）：

query {
  posts {
    id
    title
    body
  }
}

4. REST API

健康检查

Hub API 状态

5. SDK 示例

Python

import requests

API_KEY = "YOUR_API_KEY"
ENDPOINT = "https://api.unionskillai.com/"

headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
}

query = """
query {
  order(id: "o1") {
    id total
    user { name }
  }
}
"""

response = requests.post(ENDPOINT, json={"query": query}, headers=headers)
data = response.json()
print(data["data"]["order"])

JavaScript / Node.js

const res = await fetch('https://api.unionskillai.com/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    query: `{
      order(id: "o1") {
        id total
        user { name }
      }
    }`
  })
});
const { data } = await res.json();
console.log(data.order);

cURL

curl -X POST https://api.unionskillai.com/ \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "query": "{ order(id: \"o1\") { id total user { name } items { productId } } }"
  }'

6. 错误码

HTTP 状态码	错误码	说明
200	-	请求成功
401	UNAUTHENTICATED	缺少或无效的 API Key
400	GRAPHQL_VALIDATION_FAILED	GraphQL 查询语法错误
400	BAD_USER_INPUT	请求参数错误
500	INTERNAL_SERVER_ERROR	服务器内部错误
503	SERVICE_UNAVAILABLE	子图服务不可用

错误响应格式

{
  "errors": [
    {
      "message": "API Key required (X-API-Key header)",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

7. 在线调试

访问 sandbox.unionskillai.com 使用品牌化 Apollo Sandbox IDE，无需编写代码即可测试所有 GraphQL 查询。

支持的能力

能力	说明
Schema 浏览	自动加载完整 GraphQL Schema，支持类型搜索
查询编辑器	自动补全、语法高亮、实时验证
跨子图查询	联邦查询自动合并多个子图数据
REST 集成	通过 Connectors 调用外部 REST API