hashnode-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hashnode API Skill

Hashnode API 技能指南

Comprehensive assistance with the Hashnode GraphQL API for blog management, content creation, and user interaction on the Hashnode platform.

为在Hashnode平台上进行博客管理、内容创建和用户交互提供Hashnode GraphQL API的全面协助。

When to Use This Skill

何时使用本技能

This skill should be triggered when:

Building integrations with Hashnode blogs or publications
Querying Hashnode posts, users, or publication data
Creating, publishing, or managing blog posts via API
Implementing authentication with Hashnode Personal Access Tokens
Working with GraphQL queries or mutations for Hashnode
Debugging Hashnode API responses or error codes
Setting up pagination (cursor-based or offset-based) for Hashnode data
Implementing newsletter subscriptions, comments, or user interactions
Migrating from the legacy Hashnode API to the new GQL endpoint

在以下场景中应触发本技能：

构建与Hashnode博客或出版物的集成
查询Hashnode文章、用户或出版物数据
通过API创建、发布或管理博客文章
使用Hashnode个人访问令牌实现身份验证
处理Hashnode的GraphQL查询或变更操作
调试Hashnode API响应或错误代码
为Hashnode数据设置分页（基于游标或基于偏移量）
实现新闻订阅、评论或用户交互功能
从旧版Hashnode API迁移至新的GQL端点

Key Concepts

核心概念

API Endpoint

API 端点

All Hashnode API requests go through a single GraphQL endpoint:

Endpoint:
```
https://gql.hashnode.com
```
(POST only)
Playground: Visit the same URL in a browser to explore the API
Legacy API:
```
https://api.hashnode.com
```
is discontinued - migrate to new endpoint

所有Hashnode API请求都通过单个GraphQL端点发送：

端点：
```
https://gql.hashnode.com
```
（仅支持POST请求）
调试 playground： 在浏览器中访问同一URL即可探索API
旧版API：
```
https://api.hashnode.com
```
已停用 - 请迁移至新端点

Authentication

身份验证

Most queries work without authentication
Sensitive fields (drafts, email, etc.) require authentication
All mutations require authentication
Authentication method: Add
```
Authorization
```
header with your Personal Access Token (PAT)
Get your PAT: https://hashnode.com/settings/developer → "Generate New Token"

大多数查询无需身份验证即可使用
敏感字段（草稿、邮箱等）需要身份验证
所有变更操作都需要身份验证
身份验证方式： 在请求头中添加
```
Authorization
```
字段，值为你的个人访问令牌（PAT）
获取PAT： 访问https://hashnode.com/settings/developer → "Generate New Token"

Rate Limits

速率限制

Queries: 20,000 requests per minute
Mutations: 500 requests per minute

查询： 每分钟20,000次请求
变更： 每分钟500次请求

Caching

缓存

Almost all query responses are cached on the Edge
Cache is automatically purged when you mutate data
Check cache status in playground (bottom right: HIT/MISS)
Important: Always request the
```
id
```
field to avoid stale data

几乎所有查询响应都在边缘节点缓存
当你执行变更操作时，缓存会自动清除
可在playground中查看缓存状态（右下角：HIT/MISS）
重要提示： 务必请求
```
id
```
字段，以避免获取到过期数据

Error Codes

错误代码

Common GraphQL error codes:

```
GRAPHQL_VALIDATION_FAILED
```
- Invalid query structure
```
UNAUTHENTICATED
```
- Missing or invalid auth token
```
FORBIDDEN
```
- Insufficient permissions
```
BAD_USER_INPUT
```
- Invalid input data
```
NOT_FOUND
```
- Resource doesn't exist

常见GraphQL错误代码：

```
GRAPHQL_VALIDATION_FAILED
```
- 查询结构无效
```
UNAUTHENTICATED
```
- 缺少或无效的身份验证令牌
```
FORBIDDEN
```
- 权限不足
```
BAD_USER_INPUT
```
- 输入数据无效
```
NOT_FOUND
```
- 资源不存在

Quick Reference

快速参考

1. Fetch Publication Details

1. 获取出版物详情

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    isTeam
    title
    about {
      markdown
    }
  }
}

Get basic information about a publication by its hostname.

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    isTeam
    title
    about {
      markdown
    }
  }
}

通过主机名获取出版物的基本信息。

2. Fetch Recent Blog Posts

2. 获取最新博客文章

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    isTeam
    title
    posts(first: 10) {
      edges {
        node {
          id
          title
          brief
          url
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

Retrieve the latest 10 posts from a publication with cursor-based pagination support.

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    isTeam
    title
    posts(first: 10) {
      edges {
        node {
          id
          title
          brief
          url
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

从出版物中获取最新10篇文章，支持基于游标的分页。

3. Fetch a Single Article by Slug

3. 通过Slug获取单篇文章

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    post(slug: "the-developers-guide-to-chainlink-vrf-foundry-edition") {
      id
      title
      content {
        markdown
        html
      }
    }
  }
}

Get full content of a specific article using its slug and publication hostname.

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    post(slug: "the-developers-guide-to-chainlink-vrf-foundry-edition") {
      id
      title
      content {
        markdown
        html
      }
    }
  }
}

使用文章的slug和出版物主机名获取文章的完整内容。

4. Cursor-Based Pagination (Infinite Scroll)

4. 基于游标的分页（无限滚动）

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    posts(
      first: 10
      after: "NjQxZTc4NGY0M2NiMzc2YjAyNzNkMzU4XzIwMjMtMDMtMjVUMDQ6Mjc6NTkuNjQxWg=="
    ) {
      edges {
        node {
          id
          title
          brief
          url
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

Use

endCursor

from previous response as

after

parameter to fetch next page.

graphql

query Publication {
  publication(host: "blog.developerdao.com") {
    id
    posts(
      first: 10
      after: "NjQxZTc4NGY0M2NiMzc2YjAyNzNkMzU4XzIwMjMtMDMtMjVUMDQ6Mjc6NTkuNjQxWg=="
    ) {
      edges {
        node {
          id
          title
          brief
          url
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

将上一次响应中的

endCursor

作为

after

参数，以获取下一页数据。

5. Offset-Based Pagination (Traditional Pages)

5. 基于偏移量的分页（传统分页）

graphql

query Followers {
  user(username: "SandroVolpicella") {
    id
    followers(pageSize: 10, page: 1) {
      nodes {
        id
        username
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        previousPage
        nextPage
      }
    }
  }
}

Navigate between pages using explicit page numbers.

graphql

query Followers {
  user(username: "SandroVolpicella") {
    id
    followers(pageSize: 10, page: 1) {
      nodes {
        id
        username
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        previousPage
        nextPage
      }
    }
  }
}

使用明确的页码在页面间导航。

6. Get Entity Count (Series Count Example)

6. 获取实体数量（系列数量示例）

graphql

query SeriesCount {
  publication(host: "engineering.hashnode.com") {
    id
    seriesList(first: 0) {
      totalDocuments
    }
  }
}

Result:

json

{
  "data": {
    "publication": {
      "seriesList": {
        "totalDocuments": 3
      }
    }
  }
}

Use

totalDocuments

field to get counts without fetching all data.

graphql

query SeriesCount {
  publication(host: "engineering.hashnode.com") {
    id
    seriesList(first: 0) {
      totalDocuments
    }
  }
}

结果：

json

{
  "data": {
    "publication": {
      "seriesList": {
        "totalDocuments": 3
      }
    }
  }
}

使用

totalDocuments

字段获取数量，无需获取所有数据。

7. Fetch Posts from a Series

7. 获取系列中的文章

graphql

query Publication {
  publication(host: "lo-victoria.com") {
    id
    series(slug: "graphql") {
      id
      name
      posts(first: 10) {
        edges {
          node {
            id
            title
          }
        }
      }
    }
  }
}

Get all posts belonging to a specific series.

graphql

query Publication {
  publication(host: "lo-victoria.com") {
    id
    series(slug: "graphql") {
      id
      name
      posts(first: 10) {
        edges {
          node {
            id
            title
          }
        }
      }
    }
  }
}

获取属于特定系列的所有文章。

8. Fetch Static Pages

8. 获取静态页面

graphql

query Publication {
  publication(host: "lo-victoria.com") {
    id
    staticPages(first: 10) {
      edges {
        node {
          id
          title
          slug
        }
      }
    }
  }
}

Retrieve custom static pages like "About", "Contact", etc.

graphql

query Publication {
  publication(host: "lo-victoria.com") {
    id
    staticPages(first: 10) {
      edges {
        node {
          id
          title
          slug
        }
      }
    }
  }
}

检索自定义静态页面，如“关于我们”、“联系我们”等。

9. Fetch Single Static Page

9. 获取单个静态页面

graphql

query Publication {
  publication(host: "lo-victoria.com") {
    id
    staticPage(slug: "about") {
      id
      title
      content {
        markdown
      }
    }
  }
}

Get content of a specific static page by slug.

graphql

query Publication {
  publication(host: "lo-victoria.com") {
    id
    staticPage(slug: "about") {
      id
      title
      content {
        markdown
      }
    }
  }
}

通过slug获取特定静态页面的内容。

10. Authentication Example - Get Drafts (Requires Auth)

10. 身份验证示例 - 获取草稿（需要身份验证）

graphql

query Publication($first: Int!, $host: String) {
  publication(host: $host) {
    id
    drafts(first: $first) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
}

Headers:

json

{
  "Authorization": "your-personal-access-token-here"
}

Variables:

json

{
  "first": 10,
  "host": "your-blog-host.hashnode.dev"
}

Drafts can only be queried by the publication owner with valid authentication.

graphql

query Publication($first: Int!, $host: String) {
  publication(host: $host) {
    id
    drafts(first: $first) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
}

请求头：

json

{
  "Authorization": "your-personal-access-token-here"
}

变量：

json

{
  "first": 10,
  "host": "your-blog-host.hashnode.dev"
}

只有出版物所有者通过有效身份验证后，才能查询草稿。

Reference Files

参考文件

This skill includes comprehensive documentation in

references/

api.md - Complete Hashnode GraphQL API documentation including:
- GQL Playground overview
- Caching behavior and best practices
- Rate limits and authentication
- Status codes and error handling
- Pagination methods (cursor-based and offset-based)
- Migration guide from legacy API
- Query and mutation examples
- Full list of available queries and mutations

Use the reference files for detailed information about specific API features, error handling patterns, and advanced query techniques.

本技能在

references/

目录中包含完整文档：

api.md - 完整的Hashnode GraphQL API文档，包括：
- GQL Playground 概述
- 缓存行为及最佳实践
- 速率限制与身份验证
- 状态码与错误处理
- 分页方法（基于游标和基于偏移量）
- 从旧版API迁移指南
- 查询与变更操作示例
- 所有可用查询与变更操作的完整列表

如需了解特定API功能、错误处理模式和高级查询技术的详细信息，请查阅参考文件。

Working with This Skill

使用本技能的指南

For Beginners

面向初学者

Start by understanding the core concepts above, then explore:

API Endpoint: Test queries in the playground at https://gql.hashnode.com
Authentication: Generate your PAT at https://hashnode.com/settings/developer
Basic Queries: Try fetching publication details and blog posts first
Pagination: Start with cursor-based pagination for simple infinite scroll

先理解上述核心概念，然后探索：

API端点： 在https://gql.hashnode.com的playground中测试查询
身份验证： 在https://hashnode.com/settings/developer生成你的PAT
基础查询： 先尝试获取出版物详情和博客文章
分页： 从基于游标的分页开始，实现简单的无限滚动

For Intermediate Users

面向中级用户

Focus on:

Authentication flows: Implement PAT-based auth in your application
Error handling: Handle GraphQL error codes properly
Pagination strategies: Choose between cursor-based and offset-based based on your UI needs
Caching considerations: Always request
```
id
```
fields to avoid stale data
Content extraction: Work with both markdown and HTML content formats

重点关注：

身份验证流程： 在你的应用中实现基于PAT的身份验证
错误处理： 正确处理GraphQL错误代码
分页策略： 根据UI需求选择基于游标或基于偏移量的分页
缓存注意事项： 务必请求
```
id
```
字段，以避免获取过期数据
内容提取： 处理markdown和HTML两种内容格式

For Advanced Users

面向高级用户

Explore:

Mutations: Publishing posts, managing drafts, updating content
Complex queries: Nested queries with multiple levels (publication → series → posts)
Batch operations: Optimize API calls with GraphQL field selection
Webhook integration: Handle Hashnode webhook events
Rate limit optimization: Implement efficient request batching

探索：

变更操作： 发布文章、管理草稿、更新内容
复杂查询： 多层嵌套查询（出版物 → 系列 → 文章）
批量操作： 通过GraphQL字段选择优化API调用
Webhook集成： 处理Hashnode的Webhook事件
速率限制优化： 实现高效的请求批处理

Navigation Tips

导航技巧

Start broad → go deep: Begin with publication queries, then drill into specific posts/series
Check authentication: If you get
```
UNAUTHENTICATED
```
errors, verify your PAT is in the Authorization header
Test in playground: Use https://gql.hashnode.com to test queries before implementing
Monitor cache: Watch cache HIT/MISS status to optimize your queries
Read error messages: GraphQL errors include helpful details in the
```
extensions.code
```
field

从宽泛到深入： 先从出版物查询开始，再深入到特定文章/系列
检查身份验证： 如果遇到
```
UNAUTHENTICATED
```
错误，请验证你的PAT是否正确添加到Authorization请求头中
在playground中测试： 在实现前，先在https://gql.hashnode.com测试查询
监控缓存： 观察缓存的HIT/MISS状态，优化你的查询
阅读错误信息： GraphQL错误在
```
extensions.code
```
字段中包含有用的详细信息

Common Use Cases

常见使用场景

Building a Blog Frontend

构建博客前端

Fetch publication metadata
Get post list with pagination
Display individual posts by slug
Implement series/category navigation
Show static pages (about, contact)

获取出版物元数据
获取带分页的文章列表
通过slug展示单篇文章
实现系列/分类导航
展示静态页面（关于我们、联系我们）

Content Management Dashboard

内容管理仪表盘

Authenticate with PAT
List and manage drafts
Publish/update posts
Schedule content
Monitor analytics

使用PAT进行身份验证
列出并管理草稿
发布/更新文章
安排内容发布时间
监控分析数据

Newsletter Integration

新闻订阅集成

Subscribe/unsubscribe users
Fetch subscriber counts
Manage email preferences
Track engagement metrics

用户订阅/取消订阅
获取订阅者数量
管理邮箱偏好设置
跟踪参与度指标

Migration from Legacy API

从旧版API迁移

Update endpoint from
```
api.hashnode.com
```
to
```
gql.hashnode.com
```
Convert REST calls to GraphQL queries
Update authentication mechanism (check docs)
Adjust pagination from old format to cursor/offset-based
Update error handling for new error codes

将端点从
```
api.hashnode.com
```
更新为
```
gql.hashnode.com
```
将REST调用转换为GraphQL查询
更新身份验证机制（查阅文档）
将分页从旧格式调整为基于游标/偏移量的格式
更新错误处理以适配新的错误代码

Resources

资源

Official Documentation

官方文档

API Docs: https://apidocs.hashnode.com
Playground: https://gql.hashnode.com
Discord: Join for updates and community support
GraphQL Guide: freeCodeCamp's beginner-friendly GraphQL guide

API文档： https://apidocs.hashnode.com
Playground： https://gql.hashnode.com
Discord： 加入社区获取更新和支持
GraphQL指南： freeCodeCamp的GraphQL初学者友好指南

references/

The

api.md

reference file contains:

Complete API specification
All available queries and mutations
Detailed parameter descriptions
Authentication requirements
Code examples with proper syntax
Links to original documentation
Comprehensive error code reference

api.md

参考文件包含：

完整的API规范
所有可用的查询与变更操作
详细的参数说明
身份验证要求
语法正确的代码示例
官方文档链接
全面的错误代码参考

Important Notes

重要提示

Always request the
id
field on objects to avoid stale cached data
Rate limits are generous but respect them for production apps
Cache behavior: Most responses are cached; mutations automatically purge related cache
Breaking changes are rare and announced well in advance on Discord
Legacy API is shut down - use
```
gql.hashnode.com
```
only

务必请求
id
字段，以避免获取到过期的缓存数据
速率限制较为宽松，但生产环境应用请遵守限制
缓存行为： 大多数响应会被缓存；变更操作会自动清除相关缓存
破坏性变更极少，且会提前在Discord上公告
旧版API已停用 - 仅使用
```
gql.hashnode.com
```

Troubleshooting

故障排除

Getting UNAUTHENTICATED errors?

遇到UNAUTHENTICATED错误？

Verify your Personal Access Token is valid
Check the
```
Authorization
```
header is set correctly
Ensure you're requesting fields that require auth (drafts, email, etc.)

验证你的个人访问令牌是否有效
检查
```
Authorization
```
请求头是否设置正确
确保你请求的是需要身份验证的字段（草稿、邮箱等）

Not seeing latest data?

无法看到最新数据？

Always request the
```
id
```
field to avoid stale cached data
Check if response is HIT/MISS in playground

务必请求
```
id
```
字段，以避免获取过期的缓存数据
在playground中检查响应是HIT还是MISS

Query validation failed?

查询验证失败？

Verify your GraphQL syntax in the playground first
Check required parameters are provided
Ensure field names match the schema

先在playground中验证你的GraphQL语法
检查是否提供了必填参数
确保字段名称与 schema 匹配

Rate limit reached?

达到速率限制？

Queries: 20k/min is very generous - optimize your queries
Mutations: 500/min limit - batch operations where possible
Use caching on your end to reduce API calls

查询：每分钟20,000次请求非常宽松 - 优化你的查询
变更：每分钟500次请求限制 - 尽可能批量处理操作
在你的端侧使用缓存，减少API调用

Updating

更新

This skill was automatically generated from official Hashnode documentation. To refresh with updated documentation, regenerate the skill using the latest docs from https://apidocs.hashnode.com.

本技能由官方Hashnode文档自动生成。如需获取更新后的文档，请使用https://apidocs.hashnode.com的最新文档重新生成本技能。