API Reference

Complete reference for DCloud.dev APIs including GraphQL, JSON:API, authentication, and rate limits.

API Overview

GraphQL

POST /graphql

Query and mutate data using GraphQL

Type-safe queries

Real-time subscriptions

Introspection

Batch operations

JSON:API

GET/POST/PATCH/DELETE /jsonapi

RESTful API following JSON:API specification

Standard REST operations

Filtering & sorting

Relationships

Sparse fieldsets

Authentication

API Keys & OAuth

Public Access

Most content is publicly accessible without authentication. Simply make requests to the API endpoints.

Public API Request

fetch('https://your-site.dcloud.dev/jsonapi/node/article')
  .then(response => response.json())
  .then(data => console.log(data))

Authenticated Requests

For protected content or write operations, use OAuth 2.0 with client credentials.

Authenticated Request

const token = await getAccessToken();

fetch('https://your-site.dcloud.dev/jsonapi/node/article', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/vnd.api+json'
  }
})

GraphQL Schema

Common Queries

Fetch Articles

query GetArticles($first: Int = 10) {
  nodeArticles(first: $first, sortKey: CREATED_AT) {
    edges {
      node {
        id
        title
        body {
          processed
        }
        created
        author {
          displayName
        }
        path {
          alias
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Fetch Single Article

query GetArticle($id: ID!) {
  node(id: $id) {
    ... on NodeArticle {
      id
      title
      body {
        processed
      }
      created
      author {
        displayName
      }
      tags {
        name
      }
    }
  }
}

Schema Introspection

Explore the full schema using GraphQL introspection or the built-in GraphiQL explorer.

Open GraphiQL Explorer →

JSON:API Examples

Common Operations

List Articles with Filtering

GET /jsonapi/node/article?filter[status]=1&sort=-created&page[limit]=10

{
  "data": [
    {
      "type": "node--article",
      "id": "uuid-here",
      "attributes": {
        "title": "Article Title",
        "body": {
          "value": "Article content...",
          "processed": "<p>Article content...</p>"
        },
        "created": "2024-01-15T10:30:00Z"
      },
      "relationships": {
        "field_author": {
          "data": {
            "type": "user--user",
            "id": "author-uuid"
          }
        }
      }
    }
  ],
  "links": {
    "next": "/jsonapi/node/article?page[offset]=10"
  }
}

Include Related Resources

GET /jsonapi/node/article/uuid-here?include=field_author,field_tags

{
  "data": {
    "type": "node--article",
    "id": "uuid-here",
    "attributes": { ... },
    "relationships": { ... }
  },
  "included": [
    {
      "type": "user--user",
      "id": "author-uuid",
      "attributes": {
        "display_name": "John Doe"
      }
    }
  ]
}

Rate Limits

API Rate Limiting

1000

Requests per hour

Unauthenticated

5000

Requests per hour

Authenticated

Custom

Enterprise plans

Contact sales

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Handling

HTTP Status Codes

200Success - Request completed successfully

400Bad Request - Invalid request parameters

401Unauthorized - Authentication required

429Too Many Requests - Rate limit exceeded

500Internal Server Error - Server-side error