articles

Search and paginate through blog articles.

Query Structure


query {
  articles(
    first: Int,
    after: String,
    last: Int,
    before: String,
    query: String,
    author: String,
    language: String,
    status: String,
    tags: [String]
  ) {
    edges {
      cursor
      node {
        id
        title
        content
        author
        language
        status
        tags
        publishedAt
      }
    }
    nodes {
      id
      title
      content
      author
      language
      status
      tags
      publishedAt
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Arguments

Argument	Type	Description	Required	Default Value
first	Int	Returns the first n elements.	No	None
after	String	Returns elements after the specified cursor.	No	None
last	Int	Returns the last n elements.	No	None
before	String	Returns elements before the specified cursor.	No	None
query	String	Search query string to filter articles by content.	No	None
author	String	Filter articles by author.	No	None
language	String	Filter articles by language.	No	None
status	String	Filter articles by status (e.g., published, draft).	No	None
tags	[String]	Filter articles by tags.	No	None

Return Type

ArticleConnection

A connection to a list of Article items.

Field	Type	Description	Required
edges	[ArticleEdge]	A list of edges containing cursors and nodes.	No
nodes	[Article]	A list of article nodes.	No
pageInfo	PageInfo	Pagination information.	Yes
totalCount	Int	Total number of articles available.	No

ArticleEdge

Field	Type	Description	Required
cursor	String	Cursor for pagination.	Yes
node	Article	The article node.	Yes

Article

Field	Type	Description	Required
id	ID	Unique identifier of the article.	Yes
title	String	Title of the article.	Yes
content	String	Content/body of the article.	Yes
author	String	Author of the article.	Yes
language	String	Language of the article.	Yes
status	String	Status of the article (published, draft, etc.).	Yes
tags	[String]	Tags associated with the article.	Yes
publishedAt	String	Publication date/time in ISO 8601 format.	Yes

PageInfo

Field	Type	Description	Required
hasNextPage	Boolean	Indicates if there is a next page.	Yes
hasPreviousPage	Boolean	Indicates if there is a previous page.	Yes
startCursor	String	Cursor pointing to the first item in the page.	Yes
endCursor	String	Cursor pointing to the last item in the page.	Yes

Examples

Basic Query

Fetch the first 5 published articles.


query {
  articles(first: 5, status: "published") {
    nodes {
      id
      title
      author
      publishedAt
    }
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Advanced Query

Fetch the next 5 articles after a given cursor, filtering by author and tags, including full content.


query {
  articles(
    first: 5,
    after: "cursor123",
    author: "Jane Doe",
    tags: ["graphql", "api"],
    status: "published"
  ) {
    edges {
      cursor
      node {
        id
        title
        content
        author
        tags
        publishedAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Field Selection

Fetch articles filtering by language and search query, retrieving only id, title, and status.


query {
  articles(
    first: 3,
    query: "performance",
    language: "en"
  ) {
    nodes {
      id
      title
      status
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

cURL Example


curl -X POST https://www.mystoreurl.com/graphql/0.8.0/ \
  -H "Content-Type: application/json" \
  -d '{"query":"query { articles(first: 3, status: \"published\") { nodes { id title author publishedAt } totalCount pageInfo { hasNextPage endCursor } } }"}'

JavaScript Example


async function fetchPublishedArticles() {
  const query = `
    query {
      articles(first: 3, status: "published") {
        nodes {
          id
          title
          author
          publishedAt
        }
        totalCount
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  `;
 
  try {
    const response = await fetch('https://www.mystoreurl.com/graphql/0.8.0/', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ query }),
    });
 
    const result = await response.json();
 
    if (result.errors) {
      console.error('GraphQL errors:', result.errors);
      return;
    }
 
    console.log('Articles:', result.data.articles.nodes);
    console.log('Total articles:', result.data.articles.totalCount);
  } catch (error) {
    console.error('Network or fetch error:', error);
  }
}
 
fetchPublishedArticles();

Response Format

The response contains an articles field of type ArticleConnection. It includes:

edges: An optional list of edges, each with a cursor and an Article node.
nodes: An optional list of Article nodes.
pageInfo: Pagination details including cursors and page availability.
totalCount: The total number of articles matching the query.

Example response snippet:


{
  "data": {
    "articles": {
      "nodes": [
        {
          "id": "12345",
          "title": "GraphQL API Best Practices",
          "author": "Jane Doe",
          "publishedAt": "2024-04-01T12:00:00Z"
        }
      ],
      "totalCount": 42,
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "cursor123",
        "endCursor": "cursor456"
      }
    }
  }
}

Error Handling

The API may return errors in the following scenarios:

Error Code	Description	Handling Recommendation
`BAD_USER_INPUT`	Invalid argument types or values (e.g., negative `first` value).	Validate inputs before querying.
`QUERY_PARSE_ERROR`	Malformed GraphQL query syntax.	Check query syntax and structure.
`INTERNAL_SERVER_ERROR`	Server-side error.	Retry after some delay; contact support if persistent.
`RATE_LIMIT_EXCEEDED`	Too many requests in a short period.	Implement exponential backoff and retry.

Errors are returned in the errors array in the GraphQL response. Example:


{
  "errors": [
    {
      "message": "Argument 'first' must be a positive integer.",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Performance Considerations

Use pagination arguments (first, last, after, before) to limit the number of articles returned per request and avoid large payloads.
Leverage filtering arguments (query, author, language, status, tags) to narrow down results and reduce server load.
Avoid requesting unnecessary fields to improve response times.
Cache responses where possible, especially for queries with stable data such as published articles.
Monitor rate limits and implement retry logic with backoff to handle RATE_LIMIT_EXCEEDED errors gracefully.

Authentication

This API currently does not require authentication. However, authentication requirements may be introduced in future versions. Monitor API updates for any changes to authentication requirements.

ArticleConnection: Connection type for paginated articles.
ArticleEdge: Edge type containing cursor and article node.
Article: Article object with fields such as id, title, content, author, language, status, tags, and publishedAt.
PageInfo: Pagination metadata with cursors and page availability flags.

Notes

Pagination cursors (after, before) are opaque strings returned in the cursor field of edges.
The query argument supports full-text search within article content.
The status argument accepts values like "published" or "draft" to filter articles by publication state.
The tags argument filters articles containing any of the specified tags.
The API supports both forward and backward pagination using first/after and last/before respectively.
Always check pageInfo.hasNextPage and pageInfo.hasPreviousPage to determine if more pages are available.