Tổng quan GraphQL API

GraphQL API cung cấp một tập con được hỗ trợ của các khả năng REST của Ayrshare thông qua một endpoint duy nhất. Mỗi trường được cung cấp gọi cùng một controller bên dưới như phiên bản REST tương ứng, vì vậy xác thực, quyền sử dụng tính năng, hạn mức và dữ liệu phản hồi đều tuân theo hành vi của REST. REST vẫn là API đầy đủ hơn; hãy dùng schema hoặc Explorer để xem chính xác những thao tác nào GraphQL hỗ trợ. Điều GraphQL mang lại là khả năng yêu cầu nhiều thứ trong một request và khám phá phạm vi GraphQL đang được hỗ trợ ngay từ chính schema, mà không cần đọc tài liệu từng trang một. Schema mô tả mọi trường request được hỗ trợ và các lựa chọn có kiểu (typed selection) sẵn có trên các phản hồi có cấu trúc; các thao tác trả về envelope REST dưới dạng JSON giữ nguyên toàn bộ payload đó.

https://api.ayrshare.com/graphql

Gửi một POST với body JSON chứa một query, giống hệt như với bất kỳ endpoint GraphQL nào. GET và DELETE trả về 405 Method Not Allowed — truy vấn qua GET là tùy chọn trong đặc tả GraphQL và không được hỗ trợ tại đây.

Truy vấn đầu tiên của bạn

curl -X POST https://api.ayrshare.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ postHistory(lastDays: 7) }"}'

Phản hồi là cùng envelope JSON mà endpoint lịch sử REST trả về, được bọc trong trường data của GraphQL:

{
  "data": {
    "postHistory": {
      "history": [
        { "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }
      ],
      "refId": "9d2a7c41f0b8e6d35a1c",
      "count": 1,
      "lastUpdated": "2026-09-24T12:00:00.000Z",
      "nextUpdate": "2026-09-24T12:00:00.000Z"
    }
  }
}

Yêu cầu nhiều thứ cùng lúc

Lý do để dùng GraphQL là một request như thế này, vốn sẽ cần bốn lệnh gọi REST:

{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}

Một lượt round trip trả về cả bốn. Lưu ý rằng đây là bốn trường thao tác gốc và bốn lệnh gọi API cho mục đích tính phí, không phải một. Việc chọn các trường phản hồi lồng nhau không làm tăng số lệnh gọi — xem Giới hạn và Tính phí.

Xác thực

Giống hệt REST. Gửi API key của bạn dưới dạng bearer token:

Authorization: Bearer YOUR_API_KEY

Nếu tài khoản của bạn sử dụng User Profile, các thao tác có cung cấp profileKey có thể chọn một profile theo một trong hai cách:

Gửi Profile-Key làm giá trị mặc định cho toàn bộ request.
Truyền profileKey trên từng trường riêng lẻ để ghi đè giá trị mặc định đó, cho phép một request thao tác trên nhiều profile.

Đối số của trường được ưu tiên khi cả hai cùng có mặt. Các trường ở cấp tài khoản hoặc chỉ dành cho tài khoản chính không cung cấp profileKey và có thể từ chối header Profile-Key; ví dụ, createProfile phải dùng API key chính mà không có header đó. Hãy kiểm tra định nghĩa schema của từng trường để biết phạm vi của nó, và xem Quản lý nhiều người dùng để biết cách profile key hoạt động.

Thử mà không cần viết code

GraphQL Explorer là một trình duyệt tương tác cho schema hiện tại. Nó liệt kê mọi thao tác GraphQL sẵn có cùng các đối số và mô tả, tự động hoàn thành khi bạn gõ, và chạy truy vấn trên tài khoản của bạn. Bạn không cần API key để duyệt schema — schema là công khai, giống như tài liệu này. Bạn cần có API key để chạy truy vấn, vì mọi thao tác đều đi qua cùng cơ chế xác thực như REST.

Bạn nên dùng GraphQL hay REST?

REST vẫn là giao diện chính và là giao diện mà phần lớn tài liệu, SDK và các tích hợp của chúng tôi được xây dựng xoay quanh. Hãy dùng GraphQL khi:

Bạn cần nhiều mẩu dữ liệu không liên quan đến nhau và muốn lấy chúng trong một lượt round trip.
Bạn muốn có tên thao tác, đối số, input object, enum và các lựa chọn phản hồi có kiểu mà máy có thể đọc được. Hầu hết phản hồi vẫn là JSON để giữ nguyên toàn bộ envelope REST; createPost hiện trả về PostResult có kiểu.
Bạn đang khám phá API và muốn xem những gì hiện có mà không phải chuyển qua lại giữa các trang tài liệu.

Hãy tiếp tục dùng REST khi:

Bạn đang tải tệp lên. Dữ liệu byte của media không thể truyền qua một request GraphQL — xem Tải media lên để biết cách được hỗ trợ.
Bạn đang sử dụng một trong các SDK hoặc tích hợp no-code của chúng tôi, vốn giao tiếp bằng REST.
Bạn muốn có ít phụ thuộc nhất có thể. Một lệnh gọi REST không cần gì ngoài một HTTP client.

Cả hai giao diện đều được hỗ trợ song song, và bạn có thể kết hợp chúng tùy ý trong cùng một tích hợp.

Đọc tiếp

Sử dụng API — tìm thao tác, kiểu đối số và tải media lên.
Lỗi — những lỗi nào thay đổi mã trạng thái HTTP, vì sao các thao tác thất bại vẫn trả về HTTP 200, và cách xử lý thành công một phần.
Giới hạn và Tính phí — giới hạn kích thước truy vấn và cách tính số request.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Truy vấn đầu tiên của bạn

Yêu cầu nhiều thứ cùng lúc

Xác thực

Thử mà không cần viết code

Bạn nên dùng GraphQL hay REST?

Đọc tiếp

​Truy vấn đầu tiên của bạn

​Yêu cầu nhiều thứ cùng lúc

​Xác thực

​Thử mà không cần viết code

​Bạn nên dùng GraphQL hay REST?

​Đọc tiếp

Truy vấn đầu tiên của bạn

Yêu cầu nhiều thứ cùng lúc

Xác thực

Thử mà không cần viết code

Bạn nên dùng GraphQL hay REST?

Đọc tiếp